@k2b/ui 0.11.0 → 0.13.0

package/dist/browser/inputs/QrScanner.js

@@ -0,0 +1,164 @@
+import { template as _$template } from "solid-js/web";
+import { setAttribute as _$setAttribute } from "solid-js/web";
+import { className as _$className } from "solid-js/web";
+import { effect as _$effect } from "solid-js/web";
+import { getNextMarker as _$getNextMarker } from "solid-js/web";
+import { createComponent as _$createComponent } from "solid-js/web";
+import { getNextElement as _$getNextElement } from "solid-js/web";
+import { insert as _$insert } from "solid-js/web";
+import { memo as _$memo } from "solid-js/web";
+import { use as _$use } from "solid-js/web";
+var _tmpl$ = /*#__PURE__*/_$template(`<p class=k2b-qr-scanner__note>`),
+  _tmpl$2 = /*#__PURE__*/_$template(`<div><div class=k2b-qr-scanner__preview><video muted playsinline></video></div><p role=status></p><!$><!/>`);
+import { timed } from "@k2b/stdlib/solid";
+import { createSignal, onCleanup, onMount, Show } from "solid-js";
+import { useUiMessages } from "../intl/messages";
+/**
+ * qr-scanner turns every getUserMedia failure into the string "Camera not found.", so only the Permissions API can
+ * tell a refusal apart. Safari and Chrome expose the camera permission; elsewhere a refusal counts as unavailable.
+ */
+const cameraDenied = async () => {
+  try {
+    return (await navigator.permissions.query({
+      name: "camera"
+    })).state === "denied";
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Scans a QR code with the rear camera. Each mount owns exactly one camera session, which stops when the scanner
+ * unmounts, the page is hidden, or a result is accepted. The scanning engine loads only when the scanner mounts.
+ * Decoded content is never logged.
+ */
+export function QrScanner(props) {
+  const messages = useUiMessages();
+  const [starting, setStarting] = createSignal(true);
+  const [invalid, setInvalid] = createSignal(false);
+  let lastRejected;
+  const resetRejected = timed.debounce(() => {
+    lastRejected = undefined;
+  }, 1000);
+  const resetFeedback = timed.debounce(() => setInvalid(false), 1500);
+  let video;
+  let scanner;
+  let closed = false;
+  /** The host has unmounted the scanner; it no longer hears about failures that finish later. */
+  let unmounted = false;
+  let cleanupMotion;
+  const destroy = () => {
+    closed = true;
+    cleanupMotion?.();
+    resetRejected.cancel();
+    resetFeedback.cancel();
+    // pause(true) stops existing tracks immediately; destroy also handles a still-pending permission request.
+    void scanner?.pause(true);
+    scanner?.destroy();
+    scanner = undefined;
+  };
+  const fail = async () => {
+    if (closed) return;
+    destroy();
+    const denied = await cameraDenied();
+    if (!unmounted) props.onError(denied ? "denied" : "unavailable");
+  };
+  onMount(() => {
+    const hidden = () => {
+      if (document.visibilityState !== "visible") props.onStop();
+    };
+    const leaving = () => props.onStop();
+    document.addEventListener("visibilitychange", hidden);
+    window.addEventListener("pagehide", leaving);
+    onCleanup(() => {
+      unmounted = true;
+      destroy();
+      document.removeEventListener("visibilitychange", hidden);
+      window.removeEventListener("pagehide", leaving);
+    });
+    void (async () => {
+      try {
+        const {
+          default: Engine
+        } = await import("qr-scanner");
+        if (closed || document.visibilityState !== "visible") return;
+        scanner = new Engine(video, result => {
+          if (closed) return;
+          // Rearm only after a full second without a decoded QR, not between individual frames.
+          resetRejected.debouncedFn();
+          if (result.data === lastRejected) return;
+          if (props.onResult(result.data)) {
+            destroy();
+            return;
+          }
+          lastRejected = result.data;
+          setInvalid(true);
+          resetFeedback.debouncedFn();
+        }, {
+          preferredCamera: "environment",
+          highlightScanRegion: true,
+          // Empty frames are expected. Never log decoded content or frame data.
+          onDecodeError: error => {
+            if (closed || error === Engine.NO_QR_CODE_FOUND) return;
+            void fail();
+          }
+        });
+        const motion = matchMedia("(prefers-reduced-motion: reduce)");
+        const applyMotion = () => {
+          for (const animation of scanner?.$overlay?.getAnimations({
+            subtree: true
+          }) ?? []) {
+            if (motion.matches) animation.pause();else animation.play();
+          }
+        };
+        applyMotion();
+        motion.addEventListener("change", applyMotion);
+        cleanupMotion = () => motion.removeEventListener("change", applyMotion);
+        await scanner.start();
+        if (!closed) setStarting(false);
+      } catch {
+        await fail();
+      }
+    })();
+  });
+  return (() => {
+    var _el$ = _$getNextElement(_tmpl$2),
+      _el$2 = _el$.firstChild,
+      _el$3 = _el$2.firstChild,
+      _el$4 = _el$2.nextSibling,
+      _el$6 = _el$4.nextSibling,
+      [_el$7, _co$] = _$getNextMarker(_el$6.nextSibling);
+    var _ref$ = video;
+    typeof _ref$ === "function" ? _$use(_ref$, _el$3) : video = _el$3;
+    _$insert(_el$4, (() => {
+      var _c$ = _$memo(() => !!starting());
+      return () => _c$() ? messages().qrCameraStarting : props.instructions ?? messages().qrCameraInstructions;
+    })());
+    _$insert(_el$, _$createComponent(Show, {
+      get when() {
+        return !starting();
+      },
+      get children() {
+        var _el$5 = _$getNextElement(_tmpl$);
+        _$insert(_el$5, () => messages().qrCameraPrivacy);
+        return _el$5;
+      }
+    }), _el$7, _co$);
+    _$effect(_p$ => {
+      var _v$ = props.class ? `k2b-qr-scanner ${props.class}` : "k2b-qr-scanner",
+        _v$2 = invalid() || undefined,
+        _v$3 = messages().qrCameraPreview;
+      _v$ !== _p$.e && _$className(_el$, _p$.e = _v$);
+      _v$2 !== _p$.t && _$setAttribute(_el$2, "data-invalid", _p$.t = _v$2);
+      _v$3 !== _p$.a && _$setAttribute(_el$3, "aria-label", _p$.a = _v$3);
+      return _p$;
+    }, {
+      e: undefined,
+      t: undefined,
+      a: undefined
+    });
+    return _el$;
+  })();
+}
+export default QrScanner;
+//# sourceMappingURL=QrScanner.js.map

package/dist/browser/inputs/QrScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sources":["inputs/QrScanner.tsx"],"sourcesContent":["import { timed } from \"@k2b/stdlib/solid\";\nimport type QrScannerEngine from \"qr-scanner\";\nimport { createSignal, type JSX, onCleanup, onMount, Show } from \"solid-js\";\nimport { useUiMessages } from \"../intl/messages\";\n\nexport type QrScannerError = \"denied\" | \"unavailable\";\n\nexport type QrScannerProps = {\n  /** Decoded text is untrusted. Return `true` to accept it and stop the camera, `false` to reject it and keep scanning. */\n  onResult: (text: string) => boolean;\n  /** The page was hidden or left; unmount the scanner. */\n  onStop: () => void;\n  /** The camera could not start: access was denied, or there is no usable camera. Offer another way in. */\n  onError: (reason: QrScannerError) => void;\n  /** What to point the camera at. Defaults to a generic QR code hint. */\n  instructions?: string;\n  class?: string;\n};\n\n/**\n * qr-scanner turns every getUserMedia failure into the string \"Camera not found.\", so only the Permissions API can\n * tell a refusal apart. Safari and Chrome expose the camera permission; elsewhere a refusal counts as unavailable.\n */\nconst cameraDenied = async (): Promise<boolean> => {\n  try {\n    return (await navigator.permissions.query({ name: \"camera\" as PermissionName })).state === \"denied\";\n  } catch {\n    return false;\n  }\n};\n\n/**\n * Scans a QR code with the rear camera. Each mount owns exactly one camera session, which stops when the scanner\n * unmounts, the page is hidden, or a result is accepted. The scanning engine loads only when the scanner mounts.\n * Decoded content is never logged.\n */\nexport function QrScanner(props: QrScannerProps): JSX.Element {\n  const messages = useUiMessages();\n  const [starting, setStarting] = createSignal(true);\n  const [invalid, setInvalid] = createSignal(false);\n  let lastRejected: string | undefined;\n  const resetRejected = timed.debounce(() => {\n    lastRejected = undefined;\n  }, 1000);\n  const resetFeedback = timed.debounce(() => setInvalid(false), 1500);\n  let video!: HTMLVideoElement;\n  let scanner: QrScannerEngine | undefined;\n  let closed = false;\n  /** The host has unmounted the scanner; it no longer hears about failures that finish later. */\n  let unmounted = false;\n  let cleanupMotion: (() => void) | undefined;\n  const destroy = () => {\n    closed = true;\n    cleanupMotion?.();\n    resetRejected.cancel();\n    resetFeedback.cancel();\n    // pause(true) stops existing tracks immediately; destroy also handles a still-pending permission request.\n    void scanner?.pause(true);\n    scanner?.destroy();\n    scanner = undefined;\n  };\n  const fail = async () => {\n    if (closed) return;\n    destroy();\n    const denied = await cameraDenied();\n    if (!unmounted) props.onError(denied ? \"denied\" : \"unavailable\");\n  };\n  onMount(() => {\n    const hidden = () => {\n      if (document.visibilityState !== \"visible\") props.onStop();\n    };\n    const leaving = () => props.onStop();\n    document.addEventListener(\"visibilitychange\", hidden);\n    window.addEventListener(\"pagehide\", leaving);\n    onCleanup(() => {\n      unmounted = true;\n      destroy();\n      document.removeEventListener(\"visibilitychange\", hidden);\n      window.removeEventListener(\"pagehide\", leaving);\n    });\n    void (async () => {\n      try {\n        const { default: Engine } = await import(\"qr-scanner\");\n        if (closed || document.visibilityState !== \"visible\") return;\n        scanner = new Engine(\n          video,\n          (result) => {\n            if (closed) return;\n            // Rearm only after a full second without a decoded QR, not between individual frames.\n            resetRejected.debouncedFn();\n            if (result.data === lastRejected) return;\n            if (props.onResult(result.data)) {\n              destroy();\n              return;\n            }\n            lastRejected = result.data;\n            setInvalid(true);\n            resetFeedback.debouncedFn();\n          },\n          {\n            preferredCamera: \"environment\",\n            highlightScanRegion: true,\n            // Empty frames are expected. Never log decoded content or frame data.\n            onDecodeError: (error) => {\n              if (closed || error === Engine.NO_QR_CODE_FOUND) return;\n              void fail();\n            },\n          },\n        );\n        const motion = matchMedia(\"(prefers-reduced-motion: reduce)\");\n        const applyMotion = () => {\n          for (const animation of scanner?.$overlay?.getAnimations({ subtree: true }) ?? []) {\n            if (motion.matches) animation.pause();\n            else animation.play();\n          }\n        };\n        applyMotion();\n        motion.addEventListener(\"change\", applyMotion);\n        cleanupMotion = () => motion.removeEventListener(\"change\", applyMotion);\n        await scanner.start();\n        if (!closed) setStarting(false);\n      } catch {\n        await fail();\n      }\n    })();\n  });\n  return (\n    <div class={props.class ? `k2b-qr-scanner ${props.class}` : \"k2b-qr-scanner\"}>\n      <div class=\"k2b-qr-scanner__preview\" data-invalid={invalid() || undefined}>\n        {/* Live camera preview contains no prerecorded speech or audio. */}\n        <video ref={video} muted playsinline aria-label={messages().qrCameraPreview} />\n      </div>\n      <p role=\"status\">{starting() ? messages().qrCameraStarting : (props.instructions ?? messages().qrCameraInstructions)}</p>\n      <Show when={!starting()}>\n        <p class=\"k2b-qr-scanner__note\">{messages().qrCameraPrivacy}</p>\n      </Show>\n    </div>\n  );\n}\n\nexport default QrScanner;\n"],"mappings":"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","ignoreList":[]}

package/dist/browser/inputs/Select.js

@@ -21,19 +21,30 @@ var _tmpl$ = /*#__PURE__*/_$template(`<button type=button class="k2b-choice-cont
   _tmpl$4 = /*#__PURE__*/_$template(`<div class=k2b-choice-toolbar><!$><!/><!$><!/>`),
   _tmpl$5 = /*#__PURE__*/_$template(`<div class=k2b-choice-status><i class="ti ti-loader-2 k2b-spin"aria-hidden=true></i><span>`),
   _tmpl$6 = /*#__PURE__*/_$template(`<div class=k2b-choice-control><button type=button class=k2b-choice-trigger role=combobox aria-haspopup=listbox><!$><!/><span class=k2b-choice-trigger__value></span><i aria-hidden=true></i></button><!$><!/><!$><!/><div popover=manual class=k2b-choice-popover role=group><!$><!/><!$><!/><div class=k2b-choice-options role=listbox><!$><!/><!$><!/><!$><!/>`),
-  _tmpl$7 = /*#__PURE__*/_$template(`<i aria-hidden=true>`),
-  _tmpl$8 = /*#__PURE__*/_$template(`<span class=k2b-choice-dot aria-hidden=true>`),
-  _tmpl$9 = /*#__PURE__*/_$template(`<input type=hidden>`),
-  _tmpl$0 = /*#__PURE__*/_$template(`<div class=k2b-choice-status data-tone=danger><span></span><button type=button>`),
-  _tmpl$1 = /*#__PURE__*/_$template(`<div class=k2b-choice-status>`),
-  _tmpl$10 = /*#__PURE__*/_$template(`<button type=button class=k2b-choice-option role=option><!$><!/><span><strong></strong><!$><!/>`),
-  _tmpl$11 = /*#__PURE__*/_$template(`<small>`);
+  _tmpl$7 = /*#__PURE__*/_$template(`<span class=k2b-choice-dot data-empty=true aria-hidden=true>`),
+  _tmpl$8 = /*#__PURE__*/_$template(`<i aria-hidden=true>`),
+  _tmpl$9 = /*#__PURE__*/_$template(`<span class=k2b-choice-dot aria-hidden=true>`),
+  _tmpl$0 = /*#__PURE__*/_$template(`<input type=hidden>`),
+  _tmpl$1 = /*#__PURE__*/_$template(`<div class=k2b-choice-status data-tone=danger><span></span><button type=button>`),
+  _tmpl$10 = /*#__PURE__*/_$template(`<div class=k2b-choice-status>`),
+  _tmpl$11 = /*#__PURE__*/_$template(`<button type=button class=k2b-choice-option role=option><!$><!/><span><strong></strong><!$><!/>`),
+  _tmpl$12 = /*#__PURE__*/_$template(`<small>`);
 import { createMemo, createSignal, For, Show } from "solid-js";
 import { createFieldMeta, Field, fieldControlAria } from "../internal/field";
 import { useUiMessages } from "../intl/messages";
 import { ChoiceGroups } from "./ChoiceGroups";
 import { createChoiceLoader, createChoicePopover, filterChoiceOptions, nextEnabledChoiceIndex } from "./choice";
 import { commitFieldValue, resolveMaybeAccessor } from "./field-contract";
+
+/**
+ * `field` draws the boxed form control. `plain` shows the value as text for
+ * property rows: no box, no chevron, and a quiet surface on hover or while
+ * open. Its surface and hit area cover the nearest positioned ancestor, such as
+ * a `DescriptionList` row, so the whole row opens the picker.
+ */
+
+/** The list entry that clears a plain select. It cannot collide with a real option value. */
+const CLEAR_VALUE = "\u0000k2b-select-clear";
 const normalize = option => typeof option === "string" ? {
   value: option,
   label: option
@@ -75,6 +86,19 @@ export function Select(props) {
   // Remote loaders filter server-side; a static list has to be filtered here or
   // the search field would render but do nothing.
   const options = createMemo(() => isAsync() || !props.searchable ? groupedOptions() : props.filterOptions ? [...props.filterOptions(groupedOptions(), query())] : filterChoiceOptions(groupedOptions(), query()));
+  const plain = () => props.appearance === "plain";
+  // A plain select has no room for a clear button beside its value, so
+  // clearing becomes the last list entry, named by the placeholder.
+  const clearOption = createMemo(() => plain() && props.clearable && !query() ? {
+    value: CLEAR_VALUE,
+    label: props.placeholder ?? messages().clearSelection
+  } : undefined);
+  const listOptions = createMemo(() => {
+    const clear = clearOption();
+    return clear && !loader.error() ? [...options(), clear] : options();
+  });
+  // Colour dots mark the options, so an empty plain value keeps the column with a hollow dot.
+  const emptyDot = () => plain() && !props.placeholderIcon && sourceOptions().some(option => option.color);
   const selected = createMemo(() => {
     const current = value();
     if (current === null) return undefined;
@@ -85,29 +109,29 @@ export function Select(props) {
       label: props.selectedLabel?.() ?? current
     };
   });
-  const hasClearAction = () => Boolean(props.clearable && selected() && !props.disabled);
+  const hasClearAction = () => Boolean(props.clearable && selected() && !props.disabled && !plain());
   const accessibleLabel = () => props["aria-label"] ?? (typeof props.label === "string" ? undefined : props.placeholder ?? messages().selectOption);
   const popover = createChoicePopover(() => Boolean(props.disabled));
-  const focusedOption = () => options()[focusedIndex()];
+  const focusedOption = () => listOptions()[focusedIndex()];
   const focus = index => {
     setFocusedIndex(index);
     optionRefs[index]?.scrollIntoView({
       block: "nearest"
     });
   };
-  const move = direction => focus(nextEnabledChoiceIndex(options(), focusedIndex(), direction));
+  const move = direction => focus(nextEnabledChoiceIndex(listOptions(), focusedIndex(), direction));
   const chooseGroup = group => {
     if (group === activeGroup()) return;
     setSelectedGroup(group);
-    setFocusedIndex(nextEnabledChoiceIndex(options(), -1, 1));
+    setFocusedIndex(nextEnabledChoiceIndex(listOptions(), -1, 1));
     if (isAsync()) loader.load(query(), true);
   };
   const open = () => {
     if (props.disabled) return;
     setQuery("");
     if (isAsync()) loader.load("", true);
-    const selectedIndex = options().findIndex(option => option.value === value());
-    focus(selectedIndex >= 0 ? selectedIndex : nextEnabledChoiceIndex(options(), -1, 1));
+    const selectedIndex = listOptions().findIndex(option => option.value === (value() ?? CLEAR_VALUE));
+    focus(selectedIndex >= 0 ? selectedIndex : nextEnabledChoiceIndex(listOptions(), -1, 1));
     popover.show();
     if (isSearchable()) queueMicrotask(() => searchRef?.focus());
   };
@@ -123,6 +147,10 @@ export function Select(props) {
   const select = option => {
     if (option.disabled) return;
     close(true);
+    if (option.value === CLEAR_VALUE) {
+      commitFieldValue(props, null);
+      return;
+    }
     setCache({
       ...cache(),
       [option.value]: option
@@ -224,25 +252,54 @@ export function Select(props) {
       }), false, true);
       _$insert(_el$2, _$createComponent(Show, {
         get when() {
-          return selected()?.color;
+          return selected();
         },
         get fallback() {
           return _$createComponent(Show, {
             get when() {
-              return selected()?.icon;
+              return props.placeholderIcon;
+            },
+            get fallback() {
+              return _$createComponent(Show, {
+                get when() {
+                  return emptyDot();
+                },
+                get children() {
+                  return _$getNextElement(_tmpl$7);
+                }
+              });
             },
             children: icon => (() => {
-              var _el$35 = _$getNextElement(_tmpl$7);
-              _$effect(() => _$className(_el$35, icon()));
-              return _el$35;
+              var _el$36 = _$getNextElement(_tmpl$8);
+              _$effect(() => _$className(_el$36, `${icon()} k2b-choice-trigger__placeholder-icon`));
+              return _el$36;
             })()
           });
         },
-        children: color => (() => {
-          var _el$36 = _$getNextElement(_tmpl$8);
-          _$effect(_$p => _$setStyleProperty(_el$36, "background-color", color()));
-          return _el$36;
-        })()
+        get children() {
+          return _$createComponent(Show, {
+            get when() {
+              return selected()?.color;
+            },
+            get fallback() {
+              return _$createComponent(Show, {
+                get when() {
+                  return selected()?.icon;
+                },
+                children: icon => (() => {
+                  var _el$37 = _$getNextElement(_tmpl$8);
+                  _$effect(() => _$className(_el$37, icon()));
+                  return _el$37;
+                })()
+              });
+            },
+            children: color => (() => {
+              var _el$38 = _$getNextElement(_tmpl$9);
+              _$effect(_$p => _$setStyleProperty(_el$38, "background-color", color()));
+              return _el$38;
+            })()
+          });
+        }
       }), _el$6, _co$);
       _$insert(_el$3, () => selected()?.label ?? props.placeholder ?? messages().select);
       _$insert(_el$, _$createComponent(Show, {
@@ -250,10 +307,10 @@ export function Select(props) {
           return props.name;
         },
         children: name => (() => {
-          var _el$37 = _$getNextElement(_tmpl$9);
-          _$effect(() => _$setAttribute(_el$37, "name", name()));
-          _$effect(() => _$setProperty(_el$37, "value", value() ?? ""));
-          return _el$37;
+          var _el$39 = _$getNextElement(_tmpl$0);
+          _$effect(() => _$setAttribute(_el$39, "name", name()));
+          _$effect(() => _$setProperty(_el$39, "value", value() ?? ""));
+          return _el$39;
         })()
       }), _el$32, _co$9);
       _$insert(_el$, _$createComponent(Show, {
@@ -367,14 +424,14 @@ export function Select(props) {
           return loader.error();
         },
         children: message => (() => {
-          var _el$38 = _$getNextElement(_tmpl$0),
-            _el$39 = _el$38.firstChild,
-            _el$40 = _el$39.nextSibling;
-          _$insert(_el$39, message);
-          _$addEventListener(_el$40, "click", loader.retry, true);
-          _$insert(_el$40, () => messages().retry);
+          var _el$40 = _$getNextElement(_tmpl$1),
+            _el$41 = _el$40.firstChild,
+            _el$42 = _el$41.nextSibling;
+          _$insert(_el$41, message);
+          _$addEventListener(_el$42, "click", loader.retry, true);
+          _$insert(_el$42, () => messages().retry);
           _$runHydrationEvents();
-          return _el$38;
+          return _el$40;
         })()
       }), _el$22, _co$4);
       _$insert(_el$17, _$createComponent(Show, {
@@ -391,7 +448,7 @@ export function Select(props) {
       }), _el$24, _co$5);
       _$insert(_el$17, _$createComponent(For, {
         get each() {
-          return _$memo(() => !!loader.error())() ? [] : options();
+          return _$memo(() => !!loader.error())() ? [] : listOptions();
         },
         get fallback() {
           return _$createComponent(Show, {
@@ -399,95 +456,129 @@ export function Select(props) {
               return _$memo(() => !!!loader.loading())() && !loader.error();
             },
             get children() {
-              var _el$41 = _$getNextElement(_tmpl$1);
-              _$insert(_el$41, (() => {
+              var _el$43 = _$getNextElement(_tmpl$10);
+              _$insert(_el$43, (() => {
                 var _c$ = _$memo(() => !!isSearchable());
                 return () => _c$() ? messages().noResults : messages().noOptions;
               })());
-              return _el$41;
+              return _el$43;
             }
           });
         },
         children: (option, index) => (() => {
-          var _el$42 = _$getNextElement(_tmpl$10),
-            _el$47 = _el$42.firstChild,
-            [_el$48, _co$10] = _$getNextMarker(_el$47.nextSibling),
-            _el$43 = _el$48.nextSibling,
-            _el$44 = _el$43.firstChild,
-            _el$45 = _el$44.nextSibling,
-            [_el$46, _co$1] = _$getNextMarker(_el$45.nextSibling);
-          _el$42.$$click = () => select(option);
-          _el$42.$$pointermove = () => focus(index());
-          _$use(element => optionRefs[index()] = element, _el$42);
-          _$insert(_el$42, _$createComponent(Show, {
+          var _el$44 = _$getNextElement(_tmpl$11),
+            _el$49 = _el$44.firstChild,
+            [_el$50, _co$10] = _$getNextMarker(_el$49.nextSibling),
+            _el$45 = _el$50.nextSibling,
+            _el$46 = _el$45.firstChild,
+            _el$47 = _el$46.nextSibling,
+            [_el$48, _co$1] = _$getNextMarker(_el$47.nextSibling);
+          _el$44.$$click = () => select(option);
+          _el$44.$$pointermove = () => focus(index());
+          _$use(element => optionRefs[index()] = element, _el$44);
+          _$insert(_el$44, _$createComponent(Show, {
             get when() {
-              return option.color;
+              return option.value === CLEAR_VALUE;
             },
             get fallback() {
               return _$createComponent(Show, {
                 get when() {
-                  return option.icon;
+                  return option.color;
                 },
-                children: icon => (() => {
-                  var _el$49 = _$getNextElement(_tmpl$7);
-                  _$effect(() => _$className(_el$49, icon()));
-                  return _el$49;
+                get fallback() {
+                  return _$createComponent(Show, {
+                    get when() {
+                      return option.icon;
+                    },
+                    children: icon => (() => {
+                      var _el$51 = _$getNextElement(_tmpl$8);
+                      _$effect(() => _$className(_el$51, icon()));
+                      return _el$51;
+                    })()
+                  });
+                },
+                children: color => (() => {
+                  var _el$52 = _$getNextElement(_tmpl$9);
+                  _$effect(_$p => _$setStyleProperty(_el$52, "background-color", color()));
+                  return _el$52;
                 })()
               });
             },
-            children: color => (() => {
-              var _el$50 = _$getNextElement(_tmpl$8);
-              _$effect(_$p => _$setStyleProperty(_el$50, "background-color", color()));
-              return _el$50;
-            })()
-          }), _el$48, _co$10);
-          _$insert(_el$44, () => option.label);
-          _$insert(_el$43, _$createComponent(Show, {
+            get children() {
+              return _$createComponent(Show, {
+                get when() {
+                  return props.placeholderIcon;
+                },
+                get fallback() {
+                  return _$createComponent(Show, {
+                    get when() {
+                      return emptyDot();
+                    },
+                    get children() {
+                      return _$getNextElement(_tmpl$7);
+                    }
+                  });
+                },
+                children: icon => (() => {
+                  var _el$54 = _$getNextElement(_tmpl$8);
+                  _$effect(() => _$className(_el$54, icon()));
+                  return _el$54;
+                })()
+              });
+            }
+          }), _el$50, _co$10);
+          _$insert(_el$46, () => option.label);
+          _$insert(_el$45, _$createComponent(Show, {
             get when() {
               return option.description;
             },
             children: description => (() => {
-              var _el$51 = _$getNextElement(_tmpl$11);
-              _$insert(_el$51, description);
-              return _el$51;
+              var _el$55 = _$getNextElement(_tmpl$12);
+              _$insert(_el$55, description);
+              return _el$55;
             })()
-          }), _el$46, _co$1);
+          }), _el$48, _co$1);
           _$effect(_p$ => {
-            var _v$10 = `${listboxId}-${index()}`,
-              _v$11 = option.label,
-              _v$12 = option.value === value(),
-              _v$13 = index() === focusedIndex() ? "true" : undefined,
-              _v$14 = option.disabled;
-            _v$10 !== _p$.e && _$setAttribute(_el$42, "id", _p$.e = _v$10);
-            _v$11 !== _p$.t && _$setAttribute(_el$42, "aria-label", _p$.t = _v$11);
-            _v$12 !== _p$.a && _$setAttribute(_el$42, "aria-selected", _p$.a = _v$12);
-            _v$13 !== _p$.o && _$setAttribute(_el$42, "data-focused", _p$.o = _v$13);
-            _v$14 !== _p$.i && _$setProperty(_el$42, "disabled", _p$.i = _v$14);
+            var _v$11 = `${listboxId}-${index()}`,
+              _v$12 = option.label,
+              _v$13 = option.value === (value() ?? CLEAR_VALUE),
+              _v$14 = index() === focusedIndex() ? "true" : undefined,
+              _v$15 = option.value === CLEAR_VALUE ? "true" : undefined,
+              _v$16 = option.disabled;
+            _v$11 !== _p$.e && _$setAttribute(_el$44, "id", _p$.e = _v$11);
+            _v$12 !== _p$.t && _$setAttribute(_el$44, "aria-label", _p$.t = _v$12);
+            _v$13 !== _p$.a && _$setAttribute(_el$44, "aria-selected", _p$.a = _v$13);
+            _v$14 !== _p$.o && _$setAttribute(_el$44, "data-focused", _p$.o = _v$14);
+            _v$15 !== _p$.i && _$setAttribute(_el$44, "data-clear", _p$.i = _v$15);
+            _v$16 !== _p$.n && _$setProperty(_el$44, "disabled", _p$.n = _v$16);
             return _p$;
           }, {
             e: undefined,
             t: undefined,
             a: undefined,
             o: undefined,
-            i: undefined
+            i: undefined,
+            n: undefined
           });
           _$runHydrationEvents();
-          return _el$42;
+          return _el$44;
         })()
       }), _el$26, _co$6);
       _$effect(_p$ => {
-        var _v$6 = error() ? "true" : undefined,
-          _v$7 = selected() ? undefined : "true",
-          _v$8 = popover.open() ? props.activeIcon ?? "ti ti-chevron-up" : props.icon ?? "ti ti-chevron-down",
-          _v$9 = typeof props.label === "string" ? props.label : props["aria-label"] ?? messages().options,
-          _v$0 = activeView(),
-          _v$1 = activeView() === "grid" ? props.gridSize ?? "md" : undefined;
-        _v$6 !== _p$.e && _$setAttribute(_el$, "data-invalid", _p$.e = _v$6);
-        _v$7 !== _p$.t && _$setAttribute(_el$3, "data-placeholder", _p$.t = _v$7);
-        _v$8 !== _p$.a && _$className(_el$4, _p$.a = _v$8);
-        _v$9 !== _p$.o && _$setAttribute(_el$8, "aria-label", _p$.o = _v$9);
-        _v$0 !== _p$.i && _$setAttribute(_el$17, "data-view", _p$.i = _v$0);
-        _v$1 !== _p$.n && _$setAttribute(_el$17, "data-grid-size", _p$.n = _v$1);
+        var _v$6 = props.appearance ?? "field",
+          _v$7 = error() ? "true" : undefined,
+          _v$8 = selected() ? undefined : "true",
+          _v$9 = `${popover.open() ? props.activeIcon ?? "ti ti-chevron-up" : props.icon ?? "ti ti-chevron-down"} k2b-choice-trigger__chevron`,
+          _v$0 = typeof props.label === "string" ? props.label : props["aria-label"] ?? messages().options,
+          _v$1 = activeView(),
+          _v$10 = activeView() === "grid" ? props.gridSize ?? "md" : undefined;
+        _v$6 !== _p$.e && _$setAttribute(_el$, "data-appearance", _p$.e = _v$6);
+        _v$7 !== _p$.t && _$setAttribute(_el$, "data-invalid", _p$.t = _v$7);
+        _v$8 !== _p$.a && _$setAttribute(_el$3, "data-placeholder", _p$.a = _v$8);
+        _v$9 !== _p$.o && _$className(_el$4, _p$.o = _v$9);
+        _v$0 !== _p$.i && _$setAttribute(_el$8, "aria-label", _p$.i = _v$0);
+        _v$1 !== _p$.n && _$setAttribute(_el$17, "data-view", _p$.n = _v$1);
+        _v$10 !== _p$.s && _$setAttribute(_el$17, "data-grid-size", _p$.s = _v$10);
         return _p$;
       }, {
         e: undefined,
@@ -495,7 +586,8 @@ export function Select(props) {
         a: undefined,
         o: undefined,
         i: undefined,
-        n: undefined
+        n: undefined,
+        s: undefined
       });
       _$runHydrationEvents();
       return _el$;