@jxsuite/ui 0.0.0 → 0.2.0

package/components/jx-textfield.json

@@ -0,0 +1,645 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "JxTextfield",
+  "tagName": "jx-textfield",
+  "observedAttributes": [
+    "value",
+    "placeholder",
+    "type",
+    "label",
+    "labelledby",
+    "describedby",
+    "invalid",
+    "disabled",
+    "readonly",
+    "required",
+    "mono",
+    "multiline",
+    "grows",
+    "rows",
+    "clearable",
+    "size",
+    "name",
+    "autocomplete",
+    "error",
+    "help"
+  ],
+  "$elements": [
+    {
+      "$ref": "./jx-icon.json"
+    }
+  ],
+  "state": {
+    "value": {
+      "type": "string",
+      "default": "",
+      "attribute": "value",
+      "description": "The field's text. Written by the reader as they type, and by the host; a write equal to what is there never moves the caret. It is written to the control's value CONTENT attribute as well as its property, which makes the control's default value whatever the field currently says. That is deliberate: the element is not form-associated (specs/ui.md §3.2), so it never hears form.reset(), and a control whose default was the authored one would snap back while the element still said something else — an element and its own control disagreeing in silence. The cost is named rather than hidden: reset() is a no-op on this field until form association lands."
+    },
+    "placeholder": {
+      "type": "string",
+      "default": "",
+      "attribute": "placeholder",
+      "description": "Shown while the field is empty. Not a label."
+    },
+    "type": {
+      "type": "string",
+      "default": "text",
+      "attribute": "type",
+      "description": "The native input type: text, search, email, url, password, number or tel."
+    },
+    "label": {
+      "type": "string",
+      "default": "",
+      "attribute": "label",
+      "description": "The accessible name, forwarded to the control as aria-label. Required unless a visible label points at the control."
+    },
+    "labelledby": {
+      "type": "string",
+      "default": "",
+      "attribute": "labelledby",
+      "description": "Forwarded to the inner control as aria-labelledby."
+    },
+    "describedby": {
+      "type": "string",
+      "default": "",
+      "attribute": "describedby",
+      "description": "Forwarded to the inner control as aria-describedby, after the field's own error and help sentences."
+    },
+    "invalid": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "invalid",
+      "description": "The value is refused: the control says aria-invalid and draws in the danger colour."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "disabled",
+      "description": "Cannot be edited or focused. Clearing is an edit, so a disabled field draws no clear button and Escape empties nothing: a host that switched the control off hears no input or change from it."
+    },
+    "readonly": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "readonly",
+      "description": "Can be focused and selected, not edited. Clearing is an edit, so a read-only field draws no clear button and Escape empties nothing."
+    },
+    "required": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "required",
+      "description": "Forwarded to the control, for the form it sits in."
+    },
+    "mono": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "mono",
+      "description": "Draws the value in the monospace face: a path, a selector, a colour."
+    },
+    "multiline": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "multiline",
+      "description": "A textarea rather than an input."
+    },
+    "grows": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "grows",
+      "description": "A multiline field takes the height of its text instead of scrolling inside a fixed box. field-sizing does the work, so nothing is measured and no handler runs per keystroke. Where the engine does not support it the field keeps the height rows asks for, and a growing field with no rows keeps the three-row box a fixed one gets — opting into growth never makes a field shorter than not opting in."
+    },
+    "rows": {
+      "type": "string",
+      "default": "",
+      "attribute": "rows",
+      "description": "How many lines a multiline field is tall before it grows. Forwarded to the textarea, and it is what a growing field falls back to on an engine without field-sizing."
+    },
+    "clearable": {
+      "type": "boolean",
+      "default": false,
+      "attribute": "clearable",
+      "description": "Draws a button inside the field that empties it, shown only while there is something to clear and the field is neither disabled nor read-only. Escape empties the field on exactly the same terms. Firefox draws no clear affordance of its own for type=search, so this is the field's own rather than the platform's."
+    },
+    "size": {
+      "type": "string",
+      "default": "md",
+      "attribute": "size",
+      "description": "sm, md or lg. The control height is the kit's, so a row of controls lines up."
+    },
+    "name": {
+      "type": "string",
+      "default": "",
+      "attribute": "name",
+      "description": "The form field name, forwarded to the control."
+    },
+    "autocomplete": {
+      "type": "string",
+      "default": "",
+      "attribute": "autocomplete",
+      "description": "The autocomplete purpose, forwarded to the control."
+    },
+    "tabindex": {
+      "type": "string",
+      "default": "",
+      "description": "Forwarded to the inner control as its tabindex, which is what makes a roving caret possible: the focusable node is the control inside, not the host, so a jx-toolbar moving focus writes this rather than reaching into a child's internals. It is a PROPERTY ONLY (el.tabindex = \"0\") and deliberately not an observed attribute: written as an attribute it would land on the host as well, and a host carrying tabindex is itself focusable, so the one control would become two tab stops. The clear button is NOT given it: it is already tabindex=\"-1\" by construction, so the field is one stop whatever the toolbar writes."
+    },
+    "error": {
+      "type": "string",
+      "default": "",
+      "attribute": "error",
+      "description": "The sentence explaining a refused value, drawn under the field and announced as it changes. Its region is permanent and empty until there is something to say, so the first refusal is announced rather than only a later one; the empty region is taken out of flow rather than hidden, so it costs no layout and stays in the accessibility tree."
+    },
+    "help": {
+      "type": "string",
+      "default": "",
+      "attribute": "help",
+      "description": "A sentence of guidance under the field."
+    },
+    "hasError": {
+      "$expression": {
+        "operator": "!==",
+        "target": {
+          "$ref": "#/state/error"
+        },
+        "value": ""
+      }
+    },
+    "hasHelp": {
+      "$expression": {
+        "operator": "!==",
+        "target": {
+          "$ref": "#/state/help"
+        },
+        "value": ""
+      }
+    },
+    "isEmpty": {
+      "$expression": {
+        "operator": "===",
+        "target": {
+          "$ref": "#/state/value"
+        },
+        "value": ""
+      }
+    },
+    "isLocked": {
+      "$expression": {
+        "operator": "||",
+        "target": {
+          "$ref": "#/state/disabled"
+        },
+        "value": {
+          "$ref": "#/state/readonly"
+        }
+      }
+    },
+    "showClear": {
+      "$expression": {
+        "operator": "&&",
+        "target": {
+          "operator": "&&",
+          "target": {
+            "$ref": "#/state/clearable"
+          },
+          "value": {
+            "operator": "!",
+            "target": {
+              "$ref": "#/state/isEmpty"
+            }
+          }
+        },
+        "value": {
+          "operator": "!",
+          "target": {
+            "$ref": "#/state/isLocked"
+          }
+        }
+      }
+    },
+    "uid": {
+      "type": "string",
+      "default": "",
+      "description": "This field's own id stem, minted on mount. The error and help sentences take their ids from it, and the control names those ids in aria-describedby."
+    },
+    "onMount": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/textfield.ts",
+      "$export": "mintFieldId",
+      "description": "Mints the field's id stem, so the sentences under it can describe the control rather than only being announced once as they change."
+    },
+    "onInput": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "operator": "=",
+          "target": {
+            "$ref": "#/state/value"
+          },
+          "value": {
+            "$ref": "event#/target/value"
+          }
+        }
+      ],
+      "description": "Mirrors what the reader types into value. The native input and change events bubble from the control as they always do."
+    },
+    "onClear": {
+      "$prototype": "Function",
+      "$src": "jx-ui:/behaviors/textfield.ts",
+      "$export": "clearField",
+      "emits": [
+        {
+          "name": "input",
+          "description": "The value was emptied by the clear button; e.target is the field."
+        },
+        {
+          "name": "change",
+          "description": "The edit the clear button made is finished; e.target is the field."
+        }
+      ],
+      "description": "The clear button empties the value, puts focus back on the control the reader was in, and says so with input and then change. Both come from the element rather than from the button, so a host reading e.target.value reads the field."
+    },
+    "onClearPointerDown": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "preventDefault": true
+        }
+      ],
+      "description": "Keeps focus in the control while the clear button is pressed. Without it the press moves focus to the button, the control blurs and fires its own native change carrying the value the reader is about to delete, and the clear then fires a second one: two committed edits, and two undo entries, for one gesture."
+    },
+    "onKeydown": {
+      "$prototype": "Function",
+      "body": [
+        {
+          "$switch": {
+            "$ref": "event#/key"
+          },
+          "cases": {
+            "Escape": [
+              {
+                "if": {
+                  "$ref": "#/state/showClear"
+                },
+                "then": [
+                  {
+                    "preventDefault": true
+                  },
+                  {
+                    "operator": "=",
+                    "target": {
+                      "$ref": "#/state/value"
+                    },
+                    "value": ""
+                  },
+                  {
+                    "dispatchEvent": "input",
+                    "bubbles": true
+                  },
+                  {
+                    "dispatchEvent": "change",
+                    "bubbles": true
+                  }
+                ]
+              }
+            ],
+            "Enter": [
+              {
+                "if": {
+                  "operator": "&&",
+                  "target": {
+                    "operator": "===",
+                    "target": {
+                      "$ref": "#/state/type"
+                    },
+                    "value": "search"
+                  },
+                  "value": {
+                    "operator": "!",
+                    "target": {
+                      "$ref": "#/state/multiline"
+                    }
+                  }
+                },
+                "then": [
+                  {
+                    "preventDefault": true
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "emits": [
+        {
+          "name": "input",
+          "description": "Escape emptied a clearable field; e.target is the field."
+        },
+        {
+          "name": "change",
+          "description": "Escape finished emptying a clearable field; e.target is the field."
+        }
+      ],
+      "description": "Two keys, and nothing else. Escape empties a clearable field that has something in it, and cancels so the key does not also close whatever the field sits in. Enter is cancelled on a single-line search field: a search input inside a form submits it, and a search field is the one kind that never means to — the element owns no form, so the guard lives here rather than at every call site. A textarea never submits on Enter, so a multiline field keeps the key and the reader keeps the newline."
+    }
+  },
+  "onkeydown": {
+    "$ref": "#/state/onKeydown"
+  },
+  "attributes": {
+    "data-size": "${state.size}",
+    "data-invalid": "${state.invalid ? '' : null}",
+    "data-mono": "${state.mono ? '' : null}",
+    "data-disabled": "${state.disabled ? '' : null}",
+    "data-clearable": "${state.clearable ? '' : null}",
+    "data-multiline": "${state.multiline ? '' : null}",
+    "data-grows": "${state.grows ? '' : null}",
+    "data-rows": "${state.rows || null}"
+  },
+  "style": {
+    "display": "inline-flex",
+    "position": "relative",
+    "flexDirection": "column",
+    "gap": "var(--jx-space-1)",
+    "verticalAlign": "middle",
+    "minWidth": "0",
+    "--jx-textfield-h": "var(--jx-control-h)",
+    "--jx-textfield-pad": "var(--jx-space-3)",
+    "--jx-textfield-pad-end": "var(--jx-textfield-pad)",
+    "&[hidden]": {
+      "display": "none"
+    },
+    "&[data-size=\"sm\"]": {
+      "--jx-textfield-h": "calc(var(--jx-control-h) - 4px)",
+      "--jx-textfield-pad": "var(--jx-space-2)"
+    },
+    "&[data-size=\"lg\"]": {
+      "--jx-textfield-h": "calc(var(--jx-control-h) + 8px)"
+    },
+    "&[data-clearable]": {
+      "--jx-textfield-pad-end": "var(--jx-textfield-h)"
+    },
+    "& [part=\"input\"]": {
+      "appearance": "none",
+      "boxSizing": "border-box",
+      "width": "100%",
+      "minHeight": "var(--jx-textfield-h)",
+      "margin": "0",
+      "paddingBlock": "0",
+      "paddingInline": "var(--jx-textfield-pad) var(--jx-textfield-pad-end)",
+      "border": "1px solid var(--jx-border-strong)",
+      "borderRadius": "var(--jx-radius-sm)",
+      "background": "var(--jx-bg-input)",
+      "color": "var(--jx-fg)",
+      "font": "inherit",
+      "fontFamily": "var(--jx-font-sans)",
+      "fontSize": "var(--jx-text-md)",
+      "lineHeight": "var(--jx-leading-md)",
+      "outline": "none",
+      "transition": "border-color var(--jx-dur-1) var(--jx-ease-out)",
+      "::placeholder": {
+        "color": "var(--jx-fg-muted)"
+      },
+      ":hover": {
+        "borderColor": "var(--jx-fg-muted)"
+      },
+      ":focus-visible": {
+        "outline": "var(--jx-focus-ring)",
+        "outlineOffset": "-1px"
+      },
+      ":disabled": {
+        "opacity": "0.5",
+        "cursor": "default"
+      }
+    },
+    "& textarea[part=\"input\"]": {
+      "minHeight": "calc(var(--jx-textfield-h) * 3)",
+      "paddingBlock": "var(--jx-space-2)",
+      "resize": "vertical"
+    },
+    "&[data-grows] textarea[part=\"input\"]": {
+      "fieldSizing": "content",
+      "resize": "none"
+    },
+    "&[data-grows][data-rows] textarea[part=\"input\"]": {
+      "minHeight": "0"
+    },
+    "@supports (field-sizing: content)": {
+      "&[data-grows] textarea[part=\"input\"]": {
+        "minHeight": "0"
+      }
+    },
+    "&[data-mono] [part=\"input\"]": {
+      "fontFamily": "var(--jx-font-mono)"
+    },
+    "&[data-invalid] [part=\"input\"]": {
+      "borderColor": "var(--jx-danger)"
+    },
+    "&[data-clearable] [part=\"input\"]": {
+      "::-webkit-search-cancel-button": {
+        "appearance": "none"
+      }
+    },
+    "&[data-size=\"sm\"] [part=\"input\"]": {
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "&[data-size=\"lg\"] [part=\"input\"]": {
+      "fontSize": "var(--jx-text-lg)"
+    },
+    "& [part=\"clear\"]": {
+      "$description": "The clear button sits inside the field's border, so it draws 2px under the field's height: 22px in a 24px field, and 18px in an `sm` one. The `::before` is its hit area (WCAG 2.2 SC 2.5.8, ui.md \u00a74.3): an empty pseudo-element inset by half the difference between the drawn box and the kit's control height, which is -1px on a default field and -3px on a small one, so the region that accepts the pointer is `--jx-control-h` square at every size while the glyph and its hover box stay where they were. On a large field the difference is positive and the pseudo-element is an invisible box INSIDE a button that is already over the floor, which changes nothing. jx-tab's close button is the technique; the button is absolutely positioned already, so it is its own containing block. The extension lies over the input it clears, which was true of the drawn button too, and 2px past the field's edge at `sm`, where a neighbour at the kit's 4px gap extends 2px back and the two abut.",
+      "position": "absolute",
+      "insetBlockStart": "1px",
+      "insetInlineEnd": "1px",
+      "::before": {
+        "content": "\"\"",
+        "position": "absolute",
+        "inset": "calc((var(--jx-textfield-h) - 2px - var(--jx-control-h)) / 2)"
+      },
+      "display": "inline-flex",
+      "alignItems": "center",
+      "justifyContent": "center",
+      "boxSizing": "border-box",
+      "width": "calc(var(--jx-textfield-h) - 2px)",
+      "height": "calc(var(--jx-textfield-h) - 2px)",
+      "margin": "0",
+      "padding": "0",
+      "appearance": "none",
+      "border": "0",
+      "borderRadius": "var(--jx-radius-sm)",
+      "background": "transparent",
+      "color": "var(--jx-fg-muted)",
+      "cursor": "pointer",
+      "outline": "none",
+      ":hover": {
+        "color": "var(--jx-fg)"
+      },
+      ":focus-visible": {
+        "outline": "var(--jx-focus-ring)",
+        "outlineOffset": "-1px"
+      }
+    },
+    "&[data-multiline] [part=\"clear\"]": {
+      "insetBlockStart": "calc(var(--jx-space-2) + 1px)"
+    },
+    "& [part=\"error\"], & [part=\"help\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-sm)",
+      "lineHeight": "var(--jx-leading-sm)",
+      "color": "var(--jx-fg-dim)"
+    },
+    "& [part=\"error\"]": {
+      "color": "var(--jx-danger)"
+    },
+    "& [part=\"error\"]:empty": {
+      "position": "absolute"
+    },
+    "& > [part=\"control-slot\"], & > [part=\"clear-slot\"], & > [part=\"help-slot\"]": {
+      "display": "contents"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "role": "none",
+        "part": "control-slot"
+      },
+      "$switch": {
+        "$ref": "#/state/multiline"
+      },
+      "cases": {
+        "false": {
+          "tagName": "input",
+          "attributes": {
+            "part": "input",
+            "type": "${state.type}",
+            "placeholder": "${state.placeholder || null}",
+            "aria-label": "${state.label || null}",
+            "aria-labelledby": "${state.labelledby || null}",
+            "aria-describedby": "${[state.hasError && state.uid ? state.uid + '-error' : null, state.hasHelp && state.uid ? state.uid + '-help' : null, state.describedby || null].filter(Boolean).join(' ') || null}",
+            "aria-invalid": "${state.invalid ? 'true' : null}",
+            "tabindex": "${state.tabindex || null}",
+            "name": "${state.name || null}",
+            "autocomplete": "${state.autocomplete || null}",
+            "disabled": {
+              "$ref": "#/state/disabled"
+            },
+            "readonly": {
+              "$ref": "#/state/readonly"
+            },
+            "required": {
+              "$ref": "#/state/required"
+            },
+            "value": "${state.value}"
+          },
+          "value": {
+            "$ref": "#/state/value"
+          },
+          "oninput": {
+            "$ref": "#/state/onInput"
+          }
+        },
+        "true": {
+          "tagName": "textarea",
+          "attributes": {
+            "part": "input",
+            "placeholder": "${state.placeholder || null}",
+            "rows": "${state.rows || null}",
+            "aria-label": "${state.label || null}",
+            "aria-labelledby": "${state.labelledby || null}",
+            "aria-describedby": "${[state.hasError && state.uid ? state.uid + '-error' : null, state.hasHelp && state.uid ? state.uid + '-help' : null, state.describedby || null].filter(Boolean).join(' ') || null}",
+            "aria-invalid": "${state.invalid ? 'true' : null}",
+            "tabindex": "${state.tabindex || null}",
+            "name": "${state.name || null}",
+            "autocomplete": "${state.autocomplete || null}",
+            "disabled": {
+              "$ref": "#/state/disabled"
+            },
+            "readonly": {
+              "$ref": "#/state/readonly"
+            },
+            "required": {
+              "$ref": "#/state/required"
+            }
+          },
+          "textContent": "${state.value}",
+          "value": {
+            "$ref": "#/state/value"
+          },
+          "oninput": {
+            "$ref": "#/state/onInput"
+          }
+        }
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "role": "none",
+        "part": "clear-slot"
+      },
+      "$switch": {
+        "$ref": "#/state/showClear"
+      },
+      "cases": {
+        "true": {
+          "tagName": "button",
+          "attributes": {
+            "part": "clear",
+            "type": "button",
+            "tabindex": "-1",
+            "aria-label": "Clear"
+          },
+          "onclick": {
+            "$ref": "#/state/onClear"
+          },
+          "onpointerdown": {
+            "$ref": "#/state/onClearPointerDown"
+          },
+          "children": [
+            {
+              "tagName": "jx-icon",
+              "$props": {
+                "name": "x"
+              },
+              "attributes": {
+                "part": "clear-icon"
+              }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "tagName": "p",
+      "attributes": {
+        "part": "error",
+        "id": "${state.uid ? state.uid + '-error' : null}",
+        "role": "status",
+        "aria-live": "polite"
+      },
+      "textContent": "${state.error}"
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "role": "none",
+        "part": "help-slot"
+      },
+      "$switch": {
+        "$ref": "#/state/hasHelp"
+      },
+      "cases": {
+        "true": {
+          "tagName": "p",
+          "attributes": {
+            "part": "help",
+            "id": "${state.uid ? state.uid + '-help' : null}"
+          },
+          "textContent": "${state.help}"
+        }
+      }
+    }
+  ]
+}