@threadlabs/looma 0.3.1 → 0.5.0

package/components/ui-avatar-group/ui-avatar-group.html

@@ -0,0 +1,62 @@
+<template component="ui-avatar-group" controller="./ui-avatar-group.js">
+  <defs>
+    <prop name="max" type="number" default="5">max token.</prop>
+    <prop name="label" type="string" default="People">label token.</prop>
+    <state name="overflowCount" :value="0"></state>
+  </defs>
+  <div role="group" :aria-label="label">
+    <slot></slot>
+    <span class="overflow" $ref="overflow" role="img" :hidden="not overflowCount" :aria-label="format('%s more', overflowCount)"><template
+        $value="format('+%s', overflowCount)"
+      ></template></span>
+  </div>
+  <style>
+    :host {
+      display: flex;
+      align-items: center;
+      flex-direction: row;
+      gap: 0;
+    }
+
+    /* Overlap and the separating shadow are applied by the controller: slotted avatars are nested
+     * component roots outside this style scope. */
+    :slotted(*) {
+      margin-inline-start: -0.625rem;
+      flex-shrink: 0;
+      border-radius: 999px;
+    }
+
+    :slotted(*:first-child) {
+      margin-inline-start: 0;
+    }
+
+    .overflow {
+      margin-inline-start: -0.625rem;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: 2.5rem;
+      block-size: 2.5rem;
+      border-radius: 999px;
+      border: 1px solid var(--ui-border-strong);
+      background: var(--ui-surface-elevated);
+      color: var(--ui-text-primary);
+      box-shadow:
+        var(--ui-avatar-group-overlap-shadow, -2px 0 5px -1px rgb(0 0 0 / 0.28)),
+        0 0 0 1px rgb(0 0 0 / 0.06);
+      font: inherit;
+      font-size: 0.75rem;
+      font-weight: 600;
+      flex-shrink: 0;
+    }
+
+    .overflow[hidden] {
+      display: none;
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-avatar-group/ui-avatar-group.js

@@ -0,0 +1,27 @@
+// Hides avatars beyond `max`, counts them into the "+N" badge, and overlaps the rest. Projected
+// avatars are component roots, which this component's styles do not reach, so the overlap is inline.
+export default function controller(host) {
+  const element = host.element;
+  const update = () => {
+    const max = Number(host.state.max);
+    const visible = Number.isFinite(max) ? Math.max(0, Math.floor(max)) : 0;
+    const avatars = Array.from(element.children).filter((child) => child !== host.refs.overflow);
+    avatars.forEach((avatar, index) => {
+      avatar.style.display = index >= visible ? "none" : "";
+      avatar.style.marginInlineStart = index === 0 ? "0px" : "-0.625rem";
+      avatar.style.borderRadius = "999px";
+      // Later avatars cast a soft shadow back onto the one they overlap; the first overlaps nothing.
+      avatar.style.boxShadow = index === 0
+        ? "0 0 0 1px rgb(0 0 0 / 0.06)"
+        : "var(--ui-avatar-group-overlap-shadow, -2px 0 5px -1px rgb(0 0 0 / 0.28)), 0 0 0 1px rgb(0 0 0 / 0.06)";
+    });
+    host.state.overflowCount = Math.max(0, avatars.length - visible);
+  };
+  const observer = new MutationObserver(update);
+  observer.observe(element, { childList: true });
+  const stop = host.effect(update);
+  return () => {
+    stop();
+    observer.disconnect();
+  };
+}

package/components/ui-badge/ui-badge.html

@@ -0,0 +1,94 @@
+<template component="ui-badge">
+  <defs>
+    <prop name="variant" type="solid | subtle" default="subtle">variant token.</prop>
+    <prop name="tone" type="neutral | accent | info | success | warning | danger" default="neutral">tone token.</prop>
+  </defs>
+  <span><slot></slot></span>
+  <style>
+    :host {
+      --_badge-surface: var(--ui-surface-subtle);
+      --_badge-text: var(--ui-text-secondary);
+      --_badge-border: color-mix(in srgb, var(--ui-text-secondary) 30%, transparent);
+
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      max-width: 100%;
+      padding: var(--ui-badge-padding-block, var(--ui-space-0-5)) var(--ui-badge-padding-inline, var(--ui-space-2));
+      border: 1px solid var(--ui-badge-border, var(--_badge-border));
+      border-radius: var(--ui-radius-round);
+      background: var(--ui-badge-surface, var(--_badge-surface));
+      color: var(--ui-badge-text, var(--_badge-text));
+      font-family: var(--ui-font-family-sans);
+      font-size: var(--ui-badge-font-size, var(--ui-font-size-sm));
+      font-weight: var(--ui-badge-font-weight, var(--ui-font-medium));
+      line-height: var(--ui-badge-line-height, var(--ui-line-height-tight));
+      white-space: nowrap;
+    }
+
+    :host-state([tone="accent"]) {
+      --_badge-surface: var(--ui-accent-strong-surface, var(--ui-accent-solid));
+      --_badge-border: var(--ui-accent-strong-surface, var(--ui-accent-solid));
+      --_badge-text: var(--ui-accent-on-strong, var(--ui-text-on-accent));
+    }
+
+    :host-state([tone="danger"]) {
+      --_badge-surface: var(--ui-danger-strong-surface, var(--ui-danger-solid));
+      --_badge-border: var(--ui-danger-strong-surface, var(--ui-danger-solid));
+      --_badge-text: var(--ui-danger-on-strong, var(--ui-text-on-accent));
+    }
+
+    :host-state([tone="success"]) {
+      --_badge-surface: var(--ui-success-strong-surface, var(--ui-success-solid));
+      --_badge-border: var(--ui-success-strong-surface, var(--ui-success-solid));
+      --_badge-text: var(--ui-success-on-strong, var(--ui-text-on-accent));
+    }
+
+    :host-state([tone="warning"]) {
+      --_badge-surface: var(--ui-warning-strong-surface, var(--ui-warning-solid));
+      --_badge-border: var(--ui-warning-strong-surface, var(--ui-warning-solid));
+      --_badge-text: var(--ui-warning-on-strong, var(--ui-text-on-accent));
+    }
+
+    :host-state([tone="info"]) {
+      --_badge-surface: var(--ui-info-strong-surface, var(--ui-info-solid));
+      --_badge-border: var(--ui-info-strong-surface, var(--ui-info-solid));
+      --_badge-text: var(--ui-info-on-strong, var(--ui-text-on-accent));
+    }
+
+    :host-state([variant="subtle"][tone="accent"]) {
+      --_badge-surface: var(--ui-accent-soft);
+      --_badge-border: var(--ui-accent-soft);
+      --_badge-text: var(--ui-accent-subtle-text, var(--ui-accent-solid));
+    }
+
+    :host-state([variant="subtle"][tone="danger"]) {
+      --_badge-surface: var(--ui-danger-soft);
+      --_badge-border: var(--ui-danger-soft);
+      --_badge-text: var(--ui-danger-subtle-text, var(--ui-danger-solid));
+    }
+
+    :host-state([variant="subtle"][tone="success"]) {
+      --_badge-surface: var(--ui-success-soft);
+      --_badge-border: var(--ui-success-soft);
+      --_badge-text: var(--ui-success-subtle-text, var(--ui-success-solid));
+    }
+
+    :host-state([variant="subtle"][tone="warning"]) {
+      --_badge-surface: var(--ui-warning-soft);
+      --_badge-border: var(--ui-warning-soft);
+      --_badge-text: var(--ui-warning-subtle-text, var(--ui-warning-solid));
+    }
+
+    :host-state([variant="subtle"][tone="info"]) {
+      --_badge-surface: var(--ui-info-soft);
+      --_badge-border: var(--ui-info-soft);
+      --_badge-text: var(--ui-info-subtle-text, var(--ui-info-solid));
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-button/ui-button.html

@@ -0,0 +1,198 @@
+<template component="ui-button">
+  <defs>
+    <prop name="variant" type="outline | solid | danger | ghost | link" default="outline"
+    >Visual emphasis and semantic intent. link is an inline text action that reads as a link.</prop>
+    <prop name="size" type="sm | md | lg" default="md">Control size.</prop>
+    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+  </defs>
+  <button type="button" :disabled="disabled"><slot></slot></button>
+  <style>
+    :host {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      vertical-align: middle;
+      color: var(--ui-action-secondary-text, var(--ui-text-primary));
+    }
+
+    :host-state([variant="solid"]) {
+      color: var(--ui-action-primary-text, var(--ui-text-on-accent));
+    }
+
+    :host {
+      appearance: none;
+      min-block-size: var(--ui-button-min-block-size, var(--ui-control-size-md, 2.5rem));
+      border: 1px solid var(--ui-button-border, var(--ui-border-strong));
+      border-radius: var(--ui-button-radius, var(--ui-radius-2));
+      background: var(--ui-button-surface, var(--ui-surface-elevated));
+      color: var(--ui-button-text, var(--ui-action-secondary-text, var(--ui-text-primary)));
+      font: inherit;
+      font-weight: var(--ui-font-medium, 500);
+      line-height: var(--ui-line-height-tight);
+      padding: var(--ui-space-2) var(--ui-space-3);
+      background-image: var(--ui-raised-highlight, none);
+      box-shadow: var(--ui-button-shadow, var(--ui-raised, var(--ui-shadow-xs)));
+      cursor: pointer;
+      transition:
+        background-color var(--ui-motion-fast) var(--ui-motion-ease),
+        border-color var(--ui-motion-fast) var(--ui-motion-ease),
+        color var(--ui-motion-fast) var(--ui-motion-ease),
+        box-shadow var(--ui-motion-fast) var(--ui-motion-ease),
+        transform var(--ui-motion-fast) var(--ui-motion-ease);
+      margin: 0;
+    }
+
+    @supports (text-box-trim: trim-both) {
+      :host {
+        text-box-trim: trim-both;
+        text-box-edge: cap alphabetic;
+      }
+    }
+
+    :host-state([size="sm"]) {
+      min-block-size: var(--ui-control-size-sm, 2rem);
+      padding: var(--ui-space-1) var(--ui-space-2);
+      font-size: 0.875rem;
+    }
+
+    :host-state([size="lg"]) {
+      min-block-size: var(--ui-control-size-lg, 3rem);
+      padding: var(--ui-space-3) var(--ui-space-4);
+      font-size: 1rem;
+    }
+
+    :host:hover:enabled {
+      background: var(--ui-action-secondary-surface-hover, var(--ui-surface-muted));
+      border-color: var(--ui-control-border-hover, var(--ui-border-strong));
+    }
+
+    :host:active:enabled {
+      background: var(--ui-surface-subtle);
+    }
+
+    :host-state([variant="solid"]) {
+      border-color: var(--ui-action-primary-surface, var(--ui-accent-solid));
+      background: var(--ui-action-primary-surface, var(--ui-accent-solid));
+      color: var(--ui-action-primary-text, var(--ui-text-on-accent));
+      box-shadow: var(--ui-button-solid-shadow, inset 0 1px rgb(255 255 255 / 0.16), var(--ui-shadow-xs));
+    }
+
+    :host-state([variant="solid"]):hover:enabled {
+      background: var(--ui-action-primary-surface-hover, var(--ui-accent-hover));
+      border-color: var(--ui-action-primary-surface-hover, var(--ui-accent-hover));
+      box-shadow: var(--ui-shadow-sm);
+      transform: translateY(-1px);
+    }
+
+    :host-state([variant="solid"]):active:enabled {
+      background: var(--ui-action-primary-surface-active, var(--ui-accent-active));
+      border-color: var(--ui-action-primary-surface-active, var(--ui-accent-active));
+      box-shadow: none;
+      transform: translateY(0);
+    }
+
+    :host-state([variant="danger"]) {
+      border-color: var(--ui-danger-solid);
+      background: var(--ui-danger-solid);
+      color: var(--ui-text-on-accent);
+      box-shadow: var(--ui-button-danger-shadow, inset 0 1px rgb(255 255 255 / 0.14), var(--ui-shadow-xs));
+    }
+
+    :host-state([variant="danger"]):hover:enabled {
+      background: var(--ui-danger-hover);
+      border-color: var(--ui-danger-hover);
+      box-shadow: var(--ui-shadow-sm);
+      transform: translateY(-1px);
+    }
+
+    :host-state([variant="danger"]):active:enabled {
+      box-shadow: none;
+      transform: translateY(0);
+    }
+
+    :host-state([variant="ghost"]) {
+      border-color: transparent;
+      background: transparent;
+      box-shadow: none;
+    }
+
+    /* Tints derive from the text colour, not a surface token, so hover and press show on any background. */
+    :host-state([variant="ghost"]):hover:enabled {
+      background: var(--ui-button-ghost-hover, color-mix(in srgb, currentColor 8%, transparent));
+      border-color: transparent;
+    }
+
+    :host-state([variant="ghost"]):active:enabled {
+      background: var(--ui-button-ghost-active, color-mix(in srgb, currentColor 14%, transparent));
+      border-color: transparent;
+    }
+
+    /* A soft halo that transitions in with the other box-shadow changes, layered on the raised shadow. */
+    :host:focus-visible {
+      outline: none;
+      box-shadow:
+        var(--ui-button-shadow, var(--ui-raised, var(--ui-shadow-xs))),
+        var(--ui-focus-halo);
+    }
+
+    :host-state([variant="solid"]):focus-visible {
+      box-shadow:
+        var(--ui-button-solid-shadow, inset 0 1px rgb(255 255 255 / 0.16), var(--ui-shadow-xs)),
+        var(--ui-focus-halo);
+    }
+
+    :host:disabled {
+      opacity: 0.6;
+      cursor: not-allowed;
+    }
+
+    @media (pointer: coarse) {
+      :host {
+        min-block-size: var(--ui-control-min-block-size, 2.75rem);
+      }
+    }
+
+    /* Link: an inline text action. No box, padding, or minimum height (inline targets are exempt under
+       WCAG 2.5.8); the inherited font; an underline that strengthens on hover; a visible focus ring. */
+    :host-state([variant="link"]) {
+      display: inline;
+      min-block-size: 0;
+      padding: 0;
+      border: 0;
+      border-radius: var(--ui-radius-sm, 4px);
+      background: none;
+      box-shadow: none;
+      font: inherit;
+      color: var(--ui-button-link-color, var(--ui-text-secondary));
+      text-decoration-line: underline;
+      text-decoration-thickness: 1px;
+      text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);
+      text-underline-offset: 0.2em;
+      transition: color var(--ui-motion-fast) var(--ui-motion-ease), text-decoration-color var(--ui-motion-fast) var(--ui-motion-ease);
+    }
+
+    :host-state([variant="link"]):hover:enabled {
+      color: var(--ui-button-link-hover-color, var(--ui-text-primary));
+      text-decoration-color: currentColor;
+      background: none;
+      transform: none;
+    }
+
+    :host-state([variant="link"]):active:enabled {
+      background: none;
+      transform: none;
+    }
+
+    :host-state([variant="link"]):focus-visible {
+      box-shadow: none;
+      /* Fallback keeps the ring if the token is missing: an unresolved var() would void the outline. */
+      outline: 2px solid var(--ui-focus-ring, currentColor);
+      outline-offset: 2px;
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-callout/ui-callout.html

@@ -0,0 +1,104 @@
+<template component="ui-callout">
+  <defs>
+    <prop name="tone" type="info | note | warning | success | danger" default="info">Semantic message tone.</prop>
+  </defs>
+  <div role="note">
+    <span class="icon" aria-hidden="true">
+      <svg $if="tone = 'info'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="12" cy="12" r="10"></circle>
+        <path d="M12 16v-4"></path>
+        <path d="M12 8h.01"></path>
+      </svg>
+      <svg $if="tone = 'note'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M13.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8.5L13.5 2Z"></path>
+        <path d="M13 2v7h7"></path>
+        <path d="m9.5 17.5 4-4 2 2-4 4H9.5v-2Z"></path>
+      </svg>
+      <svg $if="tone = 'warning'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="m21.73 18-8-14a2 2 0 0 0-3.46 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"></path>
+        <path d="M12 9v4"></path>
+        <path d="M12 17h.01"></path>
+      </svg>
+      <svg $if="tone = 'success'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="12" cy="12" r="10"></circle>
+        <path d="m9 12 2 2 4-4"></path>
+      </svg>
+      <svg $if="tone = 'danger'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="12" cy="12" r="10"></circle>
+        <path d="m15 9-6 6"></path>
+        <path d="m9 9 6 6"></path>
+      </svg>
+    </span>
+    <div class="content"><slot></slot></div>
+  </div>
+  <style>
+    :host {
+      --_callout-surface: var(--ui-info-soft);
+      --_callout-border: var(--ui-info-solid);
+      --_callout-icon: var(--ui-info-solid);
+
+      display: grid;
+      grid-template-columns: var(--ui-callout-icon-column, 1.125rem) minmax(0, 1fr);
+      gap: var(--ui-callout-gap, calc(var(--ui-space-2) * 0.75));
+      align-items: start;
+      max-width: 100%;
+      padding: var(--ui-callout-padding-block, var(--ui-space-2)) var(--ui-callout-padding-inline, var(--ui-space-3));
+      border: var(--ui-callout-border-width, 1px) solid color-mix(in srgb, var(--ui-callout-border, var(--_callout-border)) 35%, transparent);
+      border-inline-start: var(--ui-callout-leading-border-width, 4px) solid var(--ui-callout-border, var(--_callout-border));
+      border-radius: var(--ui-radius-2);
+      background: var(--ui-callout-surface, var(--_callout-surface));
+      color: var(--ui-callout-text, var(--ui-text-primary));
+      font-family: var(--ui-font-family-sans);
+      font-size: var(--ui-font-size-sm);
+      font-weight: var(--ui-font-normal);
+      line-height: var(--ui-line-height-md);
+    }
+
+    /* One line box tall, so the icon centres on the first line of text. */
+    .icon {
+      display: grid;
+      place-items: center;
+      inline-size: var(--ui-callout-icon-column, 1.125rem);
+      block-size: 1lh;
+      color: var(--ui-callout-icon, var(--_callout-icon));
+    }
+
+    .icon svg {
+      inline-size: var(--ui-callout-icon-size, 1.125rem);
+      block-size: var(--ui-callout-icon-size, 1.125rem);
+    }
+
+    .content {
+      min-inline-size: 0;
+    }
+
+    :host-state([tone="note"]) {
+      --_callout-surface: var(--ui-surface-muted);
+      --_callout-border: var(--ui-border-strong);
+      --_callout-icon: var(--ui-text-secondary);
+    }
+
+    :host-state([tone="warning"]) {
+      --_callout-surface: var(--ui-warning-soft);
+      --_callout-border: var(--ui-warning-solid);
+      --_callout-icon: var(--ui-warning-solid);
+    }
+
+    :host-state([tone="success"]) {
+      --_callout-surface: var(--ui-success-soft);
+      --_callout-border: var(--ui-success-solid);
+      --_callout-icon: var(--ui-success-solid);
+    }
+
+    :host-state([tone="danger"]) {
+      --_callout-surface: var(--ui-danger-soft);
+      --_callout-border: var(--ui-danger-solid);
+      --_callout-icon: var(--ui-danger-solid);
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-checkbox/ui-checkbox.html

@@ -0,0 +1,107 @@
+<template component="ui-checkbox" controller="./ui-checkbox.js">
+  <defs>
+    <prop name="checked" type="boolean" default="false">Whether the checkbox is checked initially or when set externally.</prop>
+    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="indeterminate" type="boolean" default="false">indeterminate token.</prop>
+    <prop name="required" type="boolean" default="false">required token.</prop>
+    <prop name="value" type="string" default="on">value token.</prop>
+    <state name="internalChecked" :value="false"></state>
+    <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>
+  </defs>
+  <label>
+    <input type="checkbox" $ref="input" .checked="internalChecked" .indeterminate="indeterminate" :disabled="disabled" :required="required" :value="value">
+    <span class="label"><slot></slot></span>
+  </label>
+  <style>
+    :host {
+      display: inline-flex;
+      align-items: flex-start;
+      gap: var(--ui-checkbox-gap, var(--ui-space-2));
+      max-inline-size: 100%;
+      color: var(--ui-text-primary);
+      cursor: pointer;
+    }
+
+    .label {
+      min-inline-size: 0;
+      line-height: var(--ui-line-height-md);
+    }
+
+    input {
+      appearance: none;
+      -webkit-appearance: none;
+      position: relative;
+      flex: 0 0 auto;
+      inline-size: var(--ui-checkbox-size, 1.125rem);
+      block-size: var(--ui-checkbox-size, 1.125rem);
+      margin: 0.125em 0 0;
+      border: 1px solid var(--ui-control-border-hover, var(--ui-border-strong));
+      border-radius: var(--ui-radius-1);
+      background: var(--ui-control-surface, var(--ui-surface-default));
+      box-shadow: inset 0 1px 2px color-mix(in srgb, var(--ui-text-primary) 8%, transparent);
+      cursor: pointer;
+      transition:
+        background-color var(--ui-motion-fast) var(--ui-motion-ease),
+        border-color var(--ui-motion-fast) var(--ui-motion-ease),
+        box-shadow var(--ui-motion-fast) var(--ui-motion-ease);
+    }
+
+    input::after {
+      content: "";
+      position: absolute;
+      opacity: 0;
+    }
+
+    input:checked,
+    input:indeterminate {
+      border-color: var(--ui-accent-solid);
+      background: var(--ui-accent-solid);
+      box-shadow: inset 0 1px 2px color-mix(in srgb, #000 16%, transparent);
+    }
+
+    /* Centre the tick's box, then lift it: a rotated L's ink sits ~0.11rem below its box centre. */
+    input:checked::after {
+      inset: 0;
+      margin: auto;
+      inline-size: 0.32rem;
+      block-size: 0.58rem;
+      border: solid var(--ui-text-on-accent);
+      border-width: 0 0.125rem 0.125rem 0;
+      opacity: 1;
+      transform: translateY(-0.11rem) rotate(45deg);
+    }
+
+    input:indeterminate::after {
+      inset: 50% 0.23rem auto;
+      block-size: 0.125rem;
+      border-radius: var(--ui-radius-round);
+      background: var(--ui-text-on-accent);
+      opacity: 1;
+      transform: translateY(-50%);
+    }
+
+    input:hover:enabled {
+      border-color: var(--ui-accent-solid);
+    }
+
+    input:focus-visible {
+      outline: 2px solid var(--ui-focus-ring, var(--ui-accent-solid));
+      outline-offset: 2px;
+    }
+
+    :host-state([disabled]) {
+      color: var(--ui-text-muted);
+      cursor: not-allowed;
+    }
+    :host-state([disabled]) input {
+      border-color: var(--ui-border-default);
+      background: var(--ui-control-surface-disabled, var(--ui-surface-muted));
+      cursor: not-allowed;
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-checkbox/ui-checkbox.js

@@ -0,0 +1,24 @@
+import { trackTrigger } from "../shared/trigger.js";
+
+// `checked` sets the control initially and whenever it changes; the user's changes update the state.
+export default function controller(host) {
+  const input = host.refs.input;
+  const [trigger, stopTracking] = trackTrigger(host);
+  let external = host.state.checked;
+  host.state.internalChecked = Boolean(external);
+  const stop = host.effect(() => {
+    if (host.state.checked === external) return;
+    external = host.state.checked;
+    host.state.internalChecked = Boolean(external);
+  });
+  const onChange = () => {
+    host.state.internalChecked = input.checked;
+    host.dispatch("change", { checked: input.checked, value: String(host.state.value ?? "on"), trigger: trigger() });
+  };
+  input.addEventListener("change", onChange);
+  return () => {
+    stop();
+    stopTracking();
+    input.removeEventListener("change", onChange);
+  };
+}

package/components/ui-cluster/ui-cluster.html

@@ -0,0 +1,49 @@
+<template component="ui-cluster">
+  <defs>
+    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
+    <prop name="align" type="start | center | end | stretch">align token.</prop>
+  </defs>
+  <div><slot></slot></div>
+  <style>
+    :host {
+      --_layout-gap: var(--ui-space-3, 0.75rem);
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--ui-layout-gap, var(--_layout-gap));
+      min-inline-size: 0;
+      max-inline-size: 100%;
+      margin: 0;
+    }
+
+    :host-state([gap="xs"]) {
+      --_layout-gap: var(--ui-space-2, 0.5rem);
+    }
+    :host-state([gap="s"]) {
+      --_layout-gap: var(--ui-space-3, 0.75rem);
+    }
+    :host-state([gap="m"]) {
+      --_layout-gap: var(--ui-space-4, 1rem);
+    }
+    :host-state([gap="l"]) {
+      --_layout-gap: var(--ui-space-5, 1.5rem);
+    }
+    :host-state([gap="xl"]) {
+      --_layout-gap: var(--ui-space-6, 2rem);
+    }
+    :host-state([align="start"]) {
+      align-items: flex-start;
+    }
+    :host-state([align="end"]) {
+      align-items: flex-end;
+    }
+    :host-state([align="stretch"]) {
+      align-items: stretch;
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>