@mhmo91/schmancy 0.10.34 → 0.10.36

package/skills/schmancy/SKILL.md

@@ -56,9 +56,9 @@ Use component tags (`<schmancy-menu>`, `<schmancy-dropdown>`, `<schmancy-tooltip
 
 ## Composition
 
-- **Audit by grep** (`AUDIT_BY_GREP`). An agent's compliance report on a file under a rule is the list of file:line citations of the rule's forbidden patterns; an empty list is compliance. The rule applies to every other rule in this skill (`PRIMITIVE_FIRST`, `TOKEN_FIRST_NO_ARBITRARY`, `NO_LOCAL_CLASS_CSS`, `NO_TERNARY_NOTHING_DISPATCH`): a claim that a file complies is a claim about what the file does NOT contain, and that claim is verified by enumerating the rule's forbidden patterns and grepping each one.
-  Sources: each rule above names its forbidden patterns explicitly — `TOKEN_FIRST_NO_ARBITRARY` forbids `[...]` arbitrary-value Tailwind utilities; `PRIMITIVE_FIRST` forbids raw HTML elements whose class attribute carries design-system styling (typography/color/surface/spacing-as-design); `NO_LOCAL_CLASS_CSS` forbids class/id/attribute selectors inside the `css` template; `NO_TERNARY_NOTHING_DISPATCH` forbids `${cond ? html\`...\` : nothing}` and `${cond && html\`...\`}` patterns.
-  Remediation: before reporting any file compliant, run a grep against each forbidden pattern named by the rule under audit (e.g. `grep -nE '\[(?:[^]]+)\]' <file>` for `TOKEN_FIRST_NO_ARBITRARY`; `grep -nE 'class="[^"]*\b(text-|bg-|border-|rounded-|shadow-|tracking-|leading-|p[xy]?-)' <file>` plus a manual scan for raw `<div>`/`<span>` carrying those classes for `PRIMITIVE_FIRST`). The compliance report's body is the concatenation of those grep outputs annotated with their rule name; an empty body across every pattern under every rule is the only form of "compliant". A claim of compliance unaccompanied by the grep evidence is not a compliance report and is treated as an unverified assertion that the audit loop rejects.
+- **Audit by grep** (`AUDIT_BY_GREP`). An agent's compliance report on a file under a rule is the list of file:line citations of the rule's forbidden patterns; an empty list is compliance. The rule applies to every other rule in this skill (`PRIMITIVE_FIRST`, `ARBITRARY_VALUE_CANONICAL_TOKEN_ON_REUSE`, `NO_LOCAL_CLASS_CSS`, `NO_TERNARY_NOTHING_DISPATCH`): a claim that a file complies is a claim about what the file does NOT contain, and that claim is verified by enumerating the rule's forbidden patterns and grepping each one.
+  Sources: each rule above names its forbidden patterns explicitly — `ARBITRARY_VALUE_CANONICAL_TOKEN_ON_REUSE` forbids a single-value `--<namespace>-x` `@theme` alias (the portable `[...]` arbitrary value is canonical, not forbidden); `PRIMITIVE_FIRST` forbids raw HTML elements whose class attribute carries design-system styling (typography/color/surface/spacing-as-design); `NO_LOCAL_CLASS_CSS` forbids class/id/attribute selectors inside the `css` template; `NO_TERNARY_NOTHING_DISPATCH` forbids `${cond ? html\`...\` : nothing}` and `${cond && html\`...\`}` patterns.
+  Remediation: before reporting any file compliant, run a grep against each forbidden pattern named by the rule under audit (e.g. `grep -nE '^\s*--[a-z-]+:' web/src/styles.css owl/src/**/styles.css` for single-value `@theme` aliases under `ARBITRARY_VALUE_CANONICAL_TOKEN_ON_REUSE`; `grep -nE 'class="[^"]*\b(text-|bg-|border-|rounded-|shadow-|tracking-|leading-|p[xy]?-)' <file>` plus a manual scan for raw `<div>`/`<span>` carrying those classes for `PRIMITIVE_FIRST`). The compliance report's body is the concatenation of those grep outputs annotated with their rule name; an empty body across every pattern under every rule is the only form of "compliant". A claim of compliance unaccompanied by the grep evidence is not a compliance report and is treated as an unverified assertion that the audit loop rejects.
 - **Schmancy primitive first** (`PRIMITIVE_FIRST`). Within `web/**`, every visible UI element is a custom element exported from `packages/schmancy/src/**`, and an element absent from that export set is added there before being imported into `web/**`. The rule sits above the styling rules: a `<div class="text-xs text-surface-on-variant">…</div>` whose role is typography is a violation even when every utility resolves to a registered token, because `<schmancy-typography>` already covers that role; the styling rules apply only to whatever class strings remain after the right primitive has been selected.
   Sources: [packages/schmancy/skills/schmancy/INDEX.md](../INDEX.md) catalogues the export set by job (foundations / atoms / forms / navigation / overlays / interaction / feedback / display); each role's reference file (`typography.md`, `surface.md`, `button.md`, `overlay.md`, …) names the props, slots, and events that displace the equivalent `<div>` + utility-class pattern. The export set is the single source — a primitive that is not exported from `packages/schmancy/src/**` does not satisfy this rule even if it lives in a private file inside the schmancy tree.
   Remediation: walk every `.ts` and `.html` file under `web/**` and list every raw HTML element whose class string carries design-system styling (typography, color, spacing-as-design-decision, surface, layout-as-design-decision, motion, overlay) — those are the violations. For each, look up the matching schmancy primitive in `INDEX.md` and rewrite the element through that primitive (`<schmancy-typography type=… token=…>` for type-scale text, `<schmancy-surface type=…>` for elevated/bounded surfaces (size with Tailwind utilities), `<schmancy-grid>`/`<schmancy-flex>` for layout primitives with design intent, the imperative `show`/`$notify`/`schmancyContentDrawer.push` services for overlays, `<schmancy-scroll>` for scroll containers). When a needed primitive is absent from the export set, design and implement it as a new component under `packages/schmancy/src/<role>/` — extending `SchmancyElement` with `static styles = [css\`...\`]`, registered in `HTMLElementTagNameMap`, exported through the package barrel, and documented with a sibling `.md` in the skill's reference set — and only then introduce the first call site in `web/**`. The audit subagent iterates the whole `web/**` tree, surfaces the violation list, applies the rewrites, runs `yarn workspace @momo/web tsc --noEmit` plus the colocated `*-view.test.ts` suites, and reports pre-existing violations that require a new schmancy primitive as a separate punch list for designer/architect approval before the implementation lands. The loop exits when every `web/**` file's visible UI elements are schmancy primitives and the typecheck plus the test suites pass.
@@ -113,10 +113,9 @@ When two components genuinely cannot share a signal (e.g., a generic reusable co
 **Styling**
 - Styling uses Tailwind and schmancy tokens. The `css` block in `static styles` contains only `:host` rules, `@keyframes`, and selectors targeting vendor pseudo-elements (`::-webkit-*`, `::-moz-*`). Other styling is set through Tailwind utility classes and schmancy theme tokens on the `class=` attribute. The `style=` attribute holds per-instance dynamic values only (e.g. `style="--tide: ${value}"`).
   Remediation: move declarations to Tailwind on the `class=` attribute (`backdrop-filter: blur(20px)` → `backdrop-blur-xl`; `color-mix(in oklch, Canvas 72%, transparent)` → `bg-surface/70`; `border-radius: 14px` → `rounded-2xl`; `transition: opacity 80ms linear` → `transition-opacity duration-75 ease-linear`). When a visual pattern seems to want its own class (like `.glass`), check `INDEX.md` — schmancy likely ships the component.
-- Colors: Tailwind utility classes (`bg-surface-on`, `text-primary-default`, `border-outline-variant`) are the preferred surface — every `--schmancy-sys-color-*` token is auto-aliased to `--color-*`, which Tailwind v4 turns into the full `bg-X` / `text-X` / `border-X` / `ring-X` / `fill-X` / `stroke-X` namespace. Reach for raw `var(--schmancy-sys-color-*)` only inside the `css` template literal (where Tailwind doesn't apply) or for custom tokens you've registered yourself. Never hardcoded hex.
-- **No arbitrary-value escape** (`TOKEN_FIRST_NO_ARBITRARY`). Within `web/src/**` and `packages/schmancy/src/**`, no Tailwind arbitrary-value utility (`[...]`) appears; a value not yet covered by `packages/schmancy/src/theme/theme.style.css` or the Tailwind default theme is added as a token to that file before being used. This rule supersedes the prior `TOKEN_FIRST_LITERALS_COMPLETION` annotation form: an inline `// token-gap: <namespace>` comment is no longer a valid resolution, since color and size namespaces are exhaustively covered by schmancy and Tailwind, and any uncovered namespace (aspect ratio, motion curve, custom breakpoint) is itself a token-registry extension waiting to be made.
-  Sources: `theme.md` enumerates the schmancy color tokens (every `--schmancy-sys-color-*` auto-aliases to a Tailwind class); `typography.md` enumerates the type scale; `theme.style.css` declares the spacing, radius, shadow, font, text, tracking, leading, aspect, breakpoint, container, ease, and animate namespaces, every entry of which Tailwind v4 lifts into a named utility. A bracket-syntax utility in either glob is by construction either a value the registry already covers (rule violation, replace with the token) or a value the registry does not yet cover (rule violation, extend the registry first).
-  Remediation: list every `[...]` arbitrary-value utility in the changeset; for each whose value matches a `--<namespace>-*` variable, replace with the named utility (`bg-[#faf7f2]` → `bg-surface-containerLowest`, `max-w-[720px]` → `max-w-3xl`); for each whose value has no matching variable, register the variable in `packages/schmancy/src/theme/theme.style.css` first, then mirror the same `--<namespace>-x: …` declaration inside an `@theme {}` block in the consumer's stylesheet (e.g. `web/src/styles.css`) — schmancy ships the variable to its own shadow-DOM TailwindMixin, the consumer mirror lets Tailwind v4 generate the named utility for document-scope code. When the variable lives in both places but the utility class still does not apply inside a shadow-DOM component (the mixin's utility subset is frozen at schmancy build time, so consumer-introduced class names can't be added), bind the registered variable through an inline `style="<property>: var(--<namespace>-x);"` attribute on the element — the bracket-syntax rule is satisfied because no Tailwind arbitrary-value utility appears in the markup, and the `style=` attribute consuming a registered CSS custom property fits the per-instance dynamic-value clause of `NO_LOCAL_CLASS_CSS`. When the value's design rationale is one-off (a vendor-dictated pixel width, a single-use marketing graphic) the rule still requires a registered token — the alternative is to drop the value as a design violation.
+- **Color is a theme token** (`COLOR_IS_A_THEME_TOKEN`). Every color a `web/src/**` element renders is the schmancy theme namespace surfaced as a Tailwind utility on `class=` (`text-error-default`, `bg-surface-container`, `border-outline-variant` — every `--schmancy-sys-color-*` auto-aliases to `--color-*`, which Tailwind v4 lifts into the full `bg-/text-/border-/ring-/fill-/stroke-` namespace) or a schmancy component that already carries the token (`<schmancy-surface type=…>`, `<schmancy-typography>`). A raw `#hex` / `rgb()` / `rgba()` / `hsl()` literal and an inline `var(--schmancy-sys-color-*)` inside a `style=` attribute name a color the theme already names — including inside `@keyframes` and animated backgrounds, where the animated property still references the token utility, not a hand-written value. Raw `var(--schmancy-sys-color-*)` lives only inside a component's own `static styles` `css` template (where Tailwind does not reach); a color literal in markup is admissible only with a written rationale for why no token in `theme.md` can express it. `theme.md` is the authoritative token catalog.
+- **Arbitrary value is canonical; a token is earned by semantic reuse** (`ARBITRARY_VALUE_CANONICAL_TOKEN_ON_REUSE`). Within `web/src/**`, `owl/src/**`, and `packages/schmancy/src/**`, a trivial or one-off layout/size value is its portable Tailwind arbitrary utility (`grid-rows-[auto_1fr]`, `max-w-[720px]`) and stays there; a `--<namespace>-x` `@theme` alias of a single such value is the violation and is reverted to the portable form. A `--<namespace>-*` token earns existence only as a named design concept reused across call sites — the schmancy semantic color, type-scale, spacing, and motion namespaces (`COLOR_IS_A_THEME_TOKEN` owns the color half) — never as a one-value alias. An `@theme` token is visible only to the Tailwind build that compiles its stylesheet, so a `web/src/styles.css` token emits zero CSS in `owl/`; a `suggestCanonicalClasses`-style arbitrary-value→named-utility rewrite not backed by an `@theme` declaration in the edited workspace's own build is dead CSS, and the portable arbitrary form is kept.
+- **Schmancy elements need no import in `web/src/**`** (`SCHMANCY_PLUGIN_REGISTERS`). The Vite plugin globally registers every schmancy custom element for the `web/` app; side-effect imports of individual subpaths (`import "@mhmo91/schmancy/badge"`, `import "@mhmo91/schmancy/icon"`, etc.) inside `web/src/**` are redundant and fail with TS2882. Use the tag directly in templates.
 - No `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
 
 **Accessibility (combobox forms)**

package/skills/schmancy/boat.md

@@ -1,16 +1,19 @@
 # schmancy-boat
 
-> Material-3 extended FAB that opens its panel via the `show()` overlay service. Great for persistent assistant/telemetry panels.
+> Corner-anchored launcher that opens its panel via the `show()` overlay service. Three slots, three non-overlapping intents — **no element-type sniffing**. The collapsed launcher's size, padding, radius and spacing are the consumer's; the boat owns drag, corner-snapping, position persistence and the glass surface.
 
-> **Note:** `schmancy-window` is the evolved successor with more capabilities (resize, maximize, multi-window registry). Prefer `schmancy-window` for new code unless you want the simpler FAB-to-overlay model.
+> **Note:** `schmancy-window` is the evolved successor with more capabilities (resize, maximize, multi-window registry). Prefer `schmancy-window` for new code unless you want the simpler launcher-to-overlay model.
 
 ## Usage
 ```html
-<schmancy-boat id="assistant" icon="smart_toy" label="Assistant" ?open=${isOpen}>
-  <schmancy-icon slot="header">smart_toy</schmancy-icon>
-  <span slot="summary">3</span>
+<schmancy-boat id="assistant" ?open=${isOpen}>
+  <!-- optional: slot a handle to make the boat draggable -->
+  <schmancy-icon slot="drag-handle">drag_indicator</schmancy-icon>
 
-  <!-- default slot: blooms into the show() overlay from the FAB on open -->
+  <!-- trigger slot: the collapsed launcher — a plain click opens the panel -->
+  <div slot="trigger" class="px-4 py-2 rounded-full">Assistant · 3</div>
+
+  <!-- default slot: blooms into the show() overlay on open -->
   <div class="p-4">Panel body content</div>
 </schmancy-boat>
 ```
@@ -19,11 +22,8 @@
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `id` | string | `'default'` | Unique identifier (persists drag position in localStorage) |
-| `icon` | string | — | Material icon for the FAB (overridden by the `header` slot) |
-| `label` | string | — | FAB label text. **Omit → circular icon-only FAB** |
 | `open` | boolean | `false` | Open state, reflected. Bind `?open=${…}` to drive it |
 | `corner` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Initial anchor corner |
-| `lowered` | boolean | `false` | Lower the FAB elevation |
 
 ## Methods & event
 ```typescript
@@ -36,19 +36,25 @@ boat.addEventListener('toggle', e => e.detail) // 'open' | 'closed'
 ## Slots
 | Slot | Renders | Behavior |
 |------|---------|----------|
+| `trigger` | the collapsed launcher — everything visible while closed | A native **click** (or Enter/Space) anywhere on it opens the panel. The boat does **not** `preventDefault` / `stopPropagation` / `setPointerCapture` here, so any interactive child (button, FAB, input) works natively. A child that should *not* also open the boat calls `stopPropagation()` on its own handler. |
+| `drag-handle` | the drag affordance (a grip icon, a title bar — your choice) | **Opt-in.** Pointer-drag is wired only to this slot's boat-owned wrapper. Slot something here → draggable; omit it → the boat is static at its corner. A no-move tap on the handle also opens, so the grip doubles as a launcher. |
 | _(default)_ | the expanded panel body | relocated into the `show()` overlay on open, restored on close |
-| `summary` | trailing content on the FAB pill | live count / badge — stays on the FAB |
-| `header` | leading icon on the FAB pill | overrides the `icon` property |
 
 ## Behavior
-- Drag to reposition. Releases snap to the nearest corner (FLIP + `SPRING_SMOOTH`).
-- Activation delegates to `show()`: blooms from the FAB, backdrop / Esc / back-button / focus, and sheet-on-narrow are handled by the overlay primitive.
-- Position persists in `localStorage` under `schmancy-boat-{id}`.
+- **Drag is opt-in and unambiguous.** No `<schmancy-boat>` is draggable unless the consumer slots `drag-handle`. Drag listens on a dedicated boat-owned region wrapping only that slot — every pointerdown there is a drag intent, so there is no interactive-element denylist and new interactive components never need registering.
+- **The trigger is pure content.** Opening is a normal click that bubbles; nesting a `<schmancy-button>`, `<schmancy-fab>`, etc. in the trigger Just Works — the long-standing "interactive control swallowed by the drag/tap heuristic" bug class is gone (see ADR 0031).
+- The collapsed shape is **not** imposed by the boat: no fixed height, padding, radius or gap. Style the `trigger` slot content for any shape.
+- Drag to reposition (from the handle). Releases snap to the nearest corner (FLIP + `SPRING_SMOOTH`). Position persists in `localStorage` under `schmancy-boat-{id}`.
+- Activation delegates to `show()`: blooms from the launcher, backdrop / Esc / back-button / sheet-on-narrow handled by the overlay primitive.
 - Respects `prefers-reduced-motion`.
 
 ## Example
 ```html
-<schmancy-boat id="chat" icon="chat" label="Chat" corner="bottom-right">
+<schmancy-boat id="chat" corner="bottom-right">
+  <schmancy-icon slot="drag-handle" class="px-1 opacity-40">drag_indicator</schmancy-icon>
+  <schmancy-fab slot="trigger" variant="tertiary" .label=${`Chat · ${count}`}>
+    <schmancy-icon>chat</schmancy-icon>
+  </schmancy-fab>
   <schmancy-list class="p-2">
     <!-- messages -->
   </schmancy-list>

package/skills/schmancy/fab.md

@@ -0,0 +1,75 @@
+# schmancy-fab
+
+> Material 3 Floating Action Button. Faithful to the M3 spec
+> (m3.material.io/components/floating-action-button) and the `md-fab`
+> reference implementation (github.com/material-components/material-web):
+> four colour variants, three sizes, an extended form, and a lowered
+> elevation register. Adds schmancy's house `magnetic` pull + spring press.
+
+## Usage
+```html
+<!-- Regular FAB (icon-only) -->
+<schmancy-fab aria-label="Compose"><schmancy-icon>edit</schmancy-icon></schmancy-fab>
+
+<!-- Extended FAB -->
+<schmancy-fab label="Compose" variant="primary">
+  <schmancy-icon>edit</schmancy-icon>
+</schmancy-fab>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'surface' \| 'primary' \| 'secondary' \| 'tertiary'` | `'surface'` | M3 colour role. `surface` = `surface-containerHigh` container + `primary` icon; the others use the matching `*-container` / `*-onContainer` pair |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Container size: 40 / 56 / 96 dp. Ignored while extended |
+| `label` | `string` | `''` | A non-empty value switches the FAB to its **extended** form (icon + text), exactly as `md-fab` derives extended from a truthy label |
+| `extended` | `boolean` | `false` | Reflected mirror of "`label` is non-empty"; drives the extended geometry. Set automatically from `label` — read it, don't set it |
+| `lowered` | `boolean` | `false` | M3 lowered FAB: elevation drops to level 1 (resting) / level 2 (hover) |
+
+Per M3 guidance a FAB is **never disabled** — there is no `disabled`
+property, matching `md-fab`.
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | The icon, typically `<schmancy-icon>`. Auto-sized per FAB size (24dp; 36dp for `large`) and given `aria-hidden` when an accessible name is present |
+
+## M3 tokens (exact)
+| | small | medium | large | extended |
+|--|--|--|--|--|
+| container | 40×40 | 56×56 | 96×96 | 56 tall, content wide |
+| shape (radius) | 12dp | 16dp | 28dp | 16dp |
+| icon | 24dp | 24dp | 36dp | 24dp |
+
+Extended paddings: `padding-inline-start: 16px`, `padding-inline-end: 20px`,
+icon-to-label gap `12px` — verbatim from `md-fab`'s shared styles. Label is
+the `label-large` type scale.
+
+Elevation maps to schmancy's M3 elevation tokens
+(`--schmancy-sys-elevation-*`): resting **level 3**, hover **level 4**;
+lowered → resting **level 1**, hover **level 2**. Pressed elevation equals
+resting per M3 (the press read is the state layer + spring scale).
+
+State layer: hover `0.08`, focus/pressed `0.10`, tinted with the variant's
+on-colour.
+
+## Physics (schmancy house style)
+- **magnetic** directive embedded (strength 3, radius 60px) — same pull as `schmancy-button`.
+- Hover raises elevation per M3; active applies a spring `scale(0.96)`.
+- `prefers-reduced-motion` removes the transition and the press scale.
+
+## Examples
+```html
+<!-- Small surface FAB -->
+<schmancy-fab size="small" aria-label="Add"><schmancy-icon>add</schmancy-icon></schmancy-fab>
+
+<!-- Large tertiary FAB -->
+<schmancy-fab size="large" variant="tertiary" aria-label="Create">
+  <schmancy-icon>add</schmancy-icon>
+</schmancy-fab>
+
+<!-- Lowered extended secondary FAB -->
+<schmancy-fab lowered label="New message" variant="secondary">
+  <schmancy-icon>edit</schmancy-icon>
+</schmancy-fab>
+```

package/skills/schmancy/theme.md

@@ -75,7 +75,7 @@ Every `--schmancy-sys-color-*` token is aliased as `--color-*` in the theme styl
 --schmancy-sys-color-{token}   →   --color-{token}   →   bg-{token} · text-{token} · border-{token}
 ```
 
-**Prefer the shortcut utility over the arbitrary-value escape hatch.** `border-outline-variant` is equivalent to `border-[var(--schmancy-sys-color-outlineVariant)]` but far more readable.
+**The shortcut utility is the readable form of a token that exists for genuine semantic reuse and is registered in the workspace being edited.** `border-outline-variant` reads better than `border-[var(--schmancy-sys-color-outlineVariant)]` because `outlineVariant` is a reused semantic color aliased into every consuming workspace. A trivial or one-off layout value (`grid-rows-[auto_1fr]`, `max-w-[720px]`) stays in its portable arbitrary form — aliasing it behind a workspace-local `@theme` token adds a name no second call site uses and a build dependency a sibling workspace's Tailwind does not resolve.
 
 Multi-word tokens are registered in **both** camelCase and kebab-case — both forms work. Use whichever reads better:
 

package/src/CLAUDE.md

@@ -116,10 +116,12 @@ connectedCallback() {
 ```
 
 - Every subscription ends with `.pipe(takeUntil(this.disconnecting))`.
-- Form components (`select`, `autocomplete`, `chips`) track explicit
-  property assignment with flags (`_valueSet`, `_valuesSet`) and
-  resync the visible label via `_updateInputDisplay()` in
-  `firstUpdated()` and on every programmatic value change.
+- Form components (`select`, `autocomplete`, `chips`) carry an explicit
+  `multi: boolean` mode flag and route `value` through two
+  BehaviorSubjects (`_value$`, `_values$`). They never infer mode from
+  which setter was called. Before writing a new field, read
+  `mixins/formField.mixin.ts` and mirror
+  `src/form/fields/select/select.ts` (the canonical single/multi field).
 
 ### Custom events
 
@@ -137,6 +139,13 @@ this.dispatchEvent(
 )
 ```
 
+For a **form field** (a control `<schmancy-form>` collects), emit `change`
+through the mixin's `emitChange({ value })` instead of hand-rolling
+`dispatchEvent`. It guarantees `composed: true` so the event crosses the
+shadow boundary the form listens across — the recurring field bug is a
+hand-rolled dispatch that forgets that flag. See `emitChange` in
+`mixins/formField.mixin.ts`.
+
 ### Accessibility
 
 Form components carry the ARIA combobox pattern (`role="combobox"`,
@@ -183,18 +192,15 @@ the Tailwind shortcut utilities (`bg-surface-default`,
 
 ## Validation patterns (form components)
 
-```typescript
-public checkValidity(): boolean {
-  if (!this.required) return true
-  return this.multi
-    ? this._selectedValues$.value.length > 0
-    : Boolean(this._selectedValue$.value)
-}
-
-public reportValidity(): boolean {
-  return this._inputElementRef.value?.reportValidity() ?? this.checkValidity()
-}
-```
+`checkValidity()`, `reportValidity()`, `setCustomValidity()`, the
+`validateOn` truth table, and `internals.setValidity` wiring all come from
+`FormFieldMixin` (`mixins/formField.mixin.ts`). A new field adopts them by
+extending `SchmancyFormField(styles)` — it does not hand-roll its own
+validity. The two cases that *do* require an override are array-typed
+values: empty-array `required` (the mixin's `value === ''` test passes for
+`[]`) and `setFormValue` for arrays (the platform API rejects arrays).
+`src/form/fields/select/select.ts` shows both — read it before authoring a
+field's validity.
 
 ## Pointers
 

package/src/boat/boat.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import './boat'
+import '../surface/surface'
+import type SchmancyBoat from './boat'
+
+const nextUpdate = () => new Promise(r => requestAnimationFrame(() => r(null)))
+
+// The overlay service aborts its own AbortController when an opened overlay
+// is dismissed/unmounted; that rejection is overlay-internal and out of the
+// boat's scope. Swallow ONLY AbortError so the suite stays clean without
+// masking any other unhandled rejection.
+const swallowAbort = (e: PromiseRejectionEvent) => {
+	if ((e.reason as { name?: string } | null)?.name === 'AbortError') e.preventDefault()
+}
+
+const handleWrapper = (boat: SchmancyBoat) =>
+	boat.shadowRoot!.querySelector('[aria-label="Drag to move"]') as HTMLElement
+const triggerWrapper = (boat: SchmancyBoat) =>
+	boat.shadowRoot!.querySelector('[aria-label="Open panel"]') as HTMLElement
+const container = (boat: SchmancyBoat) =>
+	boat.shadowRoot!.querySelector('schmancy-surface') as HTMLElement
+
+describe('schmancy-boat — gesture/slot contract', () => {
+	let host: HTMLDivElement
+
+	beforeEach(() => {
+		host = document.createElement('div')
+		document.body.appendChild(host)
+		localStorage.clear()
+		window.addEventListener('unhandledrejection', swallowAbort)
+	})
+
+	afterEach(async () => {
+		// Close any open overlay gracefully so show()'s teardown runs its
+		// normal finalize path instead of aborting on an abrupt DOM removal.
+		const boat = host.querySelector('schmancy-boat') as SchmancyBoat | null
+		if (boat?.open) {
+			boat.open = false
+			await nextUpdate()
+			await nextUpdate()
+		}
+		window.removeEventListener('unhandledrejection', swallowAbort)
+		host.remove()
+	})
+
+	it('is static when no drag-handle is slotted (handle region hidden)', async () => {
+		host.innerHTML = `<schmancy-boat id="a"><div slot="trigger">Open</div><div>panel</div></schmancy-boat>`
+		const boat = host.querySelector('schmancy-boat') as SchmancyBoat
+		await nextUpdate()
+		await nextUpdate()
+		expect(handleWrapper(boat).classList.contains('hidden')).toBe(true)
+	})
+
+	it('becomes draggable only when a drag-handle is slotted', async () => {
+		host.innerHTML = `<schmancy-boat id="b"><span slot="drag-handle">⠿</span><div slot="trigger">Open</div><div>panel</div></schmancy-boat>`
+		const boat = host.querySelector('schmancy-boat') as SchmancyBoat
+		await nextUpdate()
+		await nextUpdate()
+		expect(handleWrapper(boat).classList.contains('hidden')).toBe(false)
+		expect(handleWrapper(boat).classList.contains('cursor-grab')).toBe(true)
+	})
+
+	it('opens on a plain click anywhere on the trigger', async () => {
+		host.innerHTML = `<schmancy-boat id="c"><div slot="trigger">Open me</div><div>panel</div></schmancy-boat>`
+		const boat = host.querySelector('schmancy-boat') as SchmancyBoat
+		await nextUpdate()
+		expect(boat.open).toBe(false)
+		triggerWrapper(boat).click()
+		await nextUpdate()
+		expect(boat.open).toBe(true)
+	})
+
+	it('does NOT suppress a slotted interactive control (the bug class)', async () => {
+		host.innerHTML = `<schmancy-boat id="d"><button slot="trigger" id="inner">Act</button><div>panel</div></schmancy-boat>`
+		const boat = host.querySelector('schmancy-boat') as SchmancyBoat
+		const innerBtn = host.querySelector('#inner') as HTMLButtonElement
+		let innerFired = false
+		let prevented = false
+		innerBtn.addEventListener('click', e => {
+			innerFired = true
+			prevented = e.defaultPrevented
+		})
+		await nextUpdate()
+
+		innerBtn.click()
+		await nextUpdate()
+
+		// The slotted button's own handler ran, the boat did not preventDefault
+		// it, and the click still bubbled to "open" the boat.
+		expect(innerFired).toBe(true)
+		expect(prevented).toBe(false)
+		expect(boat.open).toBe(true)
+	})
+
+	it('drags from the handle and snaps (a moved gesture is not a tap-open)', async () => {
+		host.innerHTML = `<schmancy-boat id="e"><span slot="drag-handle">⠿</span><div slot="trigger">Open</div><div>panel</div></schmancy-boat>`
+		const boat = host.querySelector('schmancy-boat') as SchmancyBoat
+		await nextUpdate()
+		await nextUpdate()
+		const grip = handleWrapper(boat)
+
+		grip.dispatchEvent(
+			new PointerEvent('pointerdown', { button: 0, pointerId: 1, clientX: 100, clientY: 100, bubbles: true }),
+		)
+		window.dispatchEvent(new PointerEvent('pointermove', { pointerId: 1, clientX: 100, clientY: 100 }))
+		window.dispatchEvent(new PointerEvent('pointermove', { pointerId: 1, clientX: 220, clientY: 240 }))
+		await nextUpdate()
+		expect(container(boat).classList.contains('scale-95')).toBe(true)
+
+		window.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX: 220, clientY: 240 }))
+		await nextUpdate()
+		expect(boat.open).toBe(false)
+		expect(localStorage.getItem('schmancy-boat-e')).not.toBeNull()
+	})
+
+	it('treats a no-move press on the handle as a tap that opens', async () => {
+		host.innerHTML = `<schmancy-boat id="f"><span slot="drag-handle">⠿</span><div slot="trigger">Open</div><div>panel</div></schmancy-boat>`
+		const boat = host.querySelector('schmancy-boat') as SchmancyBoat
+		await nextUpdate()
+		await nextUpdate()
+		const grip = handleWrapper(boat)
+
+		grip.dispatchEvent(
+			new PointerEvent('pointerdown', { button: 0, pointerId: 2, clientX: 50, clientY: 50, bubbles: true }),
+		)
+		window.dispatchEvent(new PointerEvent('pointerup', { pointerId: 2, clientX: 50, clientY: 50 }))
+		await nextUpdate()
+		expect(boat.open).toBe(true)
+	})
+})