@rio-m3e/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+Rio
+Copyright 2026 LegenLee
+
+This product bundles material-color-utilities
+(https://github.com/material-foundation/material-color-utilities),
+Copyright 2021 Google LLC, licensed under the Apache License, Version 2.0.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @rio-m3e/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic logic for [Rio](https://github.com/LegenLee/rio), a Material 3 Expressive implementation: component prop types, defaults, state, and accessibility attributes, plus the DOM behaviors components share (ripple, shape morph, springs, and drag).
+
+Framework adapters such as [`@rio-m3e/vue`](https://www.npmjs.com/package/@rio-m3e/vue) are built on it, and install it for you. Install it directly only to build components of your own.
+
+Licensed under the Apache License 2.0.

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+export declare const BUTTON_VARIANTS: readonly ["filled", "tonal", "outlined", "elevated", "text"];
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+/** M3E button sizes. `small` is the default. */
+export declare const BUTTON_SIZES: readonly ["xsmall", "small", "medium", "large", "xlarge"];
+export type ButtonSize = (typeof BUTTON_SIZES)[number];
+export type ButtonShape = 'round' | 'square';
+export interface ButtonProps {
+  /** Defaults to `'filled'`. */
+  variant?: ButtonVariant;
+  /** Defaults to `'small'`. */
+  size?: ButtonSize;
+  /** Defaults to `'round'`. */
+  shape?: ButtonShape;
+  /**
+   * Makes it a toggle button, which reports `selected` changes. The spec has no toggle for text
+   * buttons, so `toggle` is ignored on them.
+   */
+  toggle?: boolean;
+  /** Whether a toggle button is on. */
+  selected?: boolean;
+  /** Native disabled: not focusable and not pressable. This is the spec's behavior. */
+  disabled?: boolean;
+  /**
+   * Disabled but still focusable, so it stays discoverable, for example in a toolbar. Clicks are
+   * blocked in JavaScript instead. This deviates from the spec, which says disabled components
+   * can't be focused.
+   */
+  softDisabled?: boolean;
+  /** Defaults to `'button'`, so a button inside a form doesn't submit it by accident. */
+  type?: 'button' | 'submit' | 'reset';
+}
+export declare const buttonDefaults: {
+  variant: "filled";
+  size: "small";
+  shape: "round";
+  toggle: false;
+  selected: false;
+  disabled: false;
+  softDisabled: false;
+  type: "button";
+};
+export interface ButtonOptions {
+  /** Returns the current prop values. The adapter owns the state. */
+  props: () => ButtonProps;
+  /** Called for a click that isn't blocked. */
+  onClick: (event: MouseEvent) => void;
+  /** Called after an unblocked click on a toggle button, with the new value. */
+  onSelectedChange: (selected: boolean) => void;
+}
+export interface ButtonApi {
+  rootAttrs: () => Record<string, string | undefined>;
+  /** Attach to the root element's `click`. */
+  handleClick: (event: MouseEvent) => void;
+}
+export declare function createButton(options: ButtonOptions): ButtonApi;
+export declare const ICON_BUTTON_VARIANTS: readonly ["filled", "tonal", "outlined", "standard"];
+export type IconButtonVariant = (typeof ICON_BUTTON_VARIANTS)[number];
+/** M3E icon button widths. `default` makes a square (or circle) as wide as it is tall. */
+export declare const ICON_BUTTON_WIDTHS: readonly ["narrow", "default", "wide"];
+export type IconButtonWidth = (typeof ICON_BUTTON_WIDTHS)[number];
+export interface IconButtonProps {
+  /**
+   * The accessible name. It should describe the action, such as "Add to favorites", not the icon,
+   * such as "Heart".
+   */
+  label: string;
+  /** Defaults to `'filled'`, the spec's default. */
+  variant?: IconButtonVariant;
+  /** Defaults to `'small'`. */
+  size?: ButtonSize;
+  /** Defaults to `'default'`. */
+  width?: IconButtonWidth;
+  /** Defaults to `'round'`. */
+  shape?: ButtonShape;
+  /** Makes it a toggle button, which reports `selected` changes. All four variants can toggle. */
+  toggle?: boolean;
+  /** Whether a toggle button is on. */
+  selected?: boolean;
+  /** Native disabled: not focusable and not pressable. This is the spec's behavior. */
+  disabled?: boolean;
+  /** Disabled but still focusable, as on the button. Deviates from the spec. */
+  softDisabled?: boolean;
+  /** Defaults to `'button'`, so it doesn't submit a form by accident. */
+  type?: 'button' | 'submit' | 'reset';
+}
+export declare const iconButtonDefaults: {
+  variant: "filled";
+  size: "small";
+  width: "default";
+  shape: "round";
+  toggle: false;
+  selected: false;
+  disabled: false;
+  softDisabled: false;
+  type: "button";
+};
+export interface IconButtonOptions {
+  /** Returns the current prop values. The adapter owns the state. */
+  props: () => IconButtonProps;
+  /** Called for a click that isn't blocked. */
+  onClick: (event: MouseEvent) => void;
+  /** Called after an unblocked click on a toggle button, with the new value. */
+  onSelectedChange: (selected: boolean) => void;
+}
+export declare function createIconButton(options: IconButtonOptions): ButtonApi;
+export interface DragInfo {
+  /** Distance from where the press started, in px. */
+  dx: number;
+  dy: number;
+  /** Over the last moments of the drag, in px per second. */
+  velocityX: number;
+  velocityY: number;
+}
+export interface DragOptions {
+  /** Pointer types that can drag. Defaults to touch and pen, as M3 specifies for the switch. */
+  pointerTypes?: readonly string[];
+  /** Distance a pointer must move before a drag starts. Defaults to 8px. */
+  threshold?: number;
+  onStart?: () => void;
+  onMove: (info: DragInfo) => void;
+  onEnd: (info: DragInfo) => void;
+  /** The browser took the pointer, for example to scroll the page. Defaults to `onEnd`. */
+  onCancel?: (info: DragInfo) => void;
+}
+export interface DragHandle {
+  detach(): void;
+}
+export declare function attachDrag(element: HTMLElement, options: DragOptions): DragHandle;
+export interface RippleHandle {
+  /** Removes the listeners and the `data-ripple` marker. */
+  detach(): void;
+}
+export interface RippleOptions {
+  /**
+   * The element that draws the ripple and sets its size, when it isn't the element that receives
+   * presses. A switch, for example, takes presses on its whole track but ripples in the circle
+   * around its handle. Defaults to the element itself.
+   */
+  surface?: HTMLElement;
+}
+/**
+ * Adds a press ripple to an element. While pressed, the element (and its surface) has
+ * `data-pressed`. Load `@rio-m3e/styles/base/ripple.css` for the visuals; it styles elements
+ * marked `data-ripple`.
+ */
+export declare function attachRipple(element: HTMLElement, options?: RippleOptions): RippleHandle;
+export interface ShapeMorphOptions {
+  /** The motion token whose spring drives the morph. Defaults to `'fast-spatial'`. */
+  token?: string;
+  /** Attributes whose changes can move the target. Defaults to Rio's state attributes. */
+  watch?: string[];
+}
+export interface ShapeMorphHandle {
+  detach(): void;
+}
+export declare function attachShapeMorph(element: HTMLElement, options?: ShapeMorphOptions): ShapeMorphHandle;
+export interface SpringPropertyOptions {
+  /** A registered <length> custom property that holds the target for the current state. */
+  target: string;
+  /** Writes the animated value in px, or clears it with `undefined` at rest. */
+  apply: (value: number | undefined) => void;
+  /** The motion token whose spring drives the value. Defaults to `'fast-spatial'`. */
+  token?: string;
+  /** Attributes whose changes can move the target. Defaults to Rio's state attributes. */
+  watch?: string[];
+}
+export interface SpringPropertyHandle {
+  /** The current animated value. */
+  readonly value: number;
+  /** Takes manual control and sets the value at once, for example while dragging. */
+  hold(value: number): void;
+  /** Gives control back: springs from the held value to the CSS target, starting at `velocity`. */
+  release(velocity?: number): void;
+  detach(): void;
+}
+/** The data attributes Rio's components use for state. */
+export declare const STATE_ATTRIBUTES: string[];
+export declare function attachSpringProperty(element: HTMLElement, options: SpringPropertyOptions): SpringPropertyHandle;
+export interface SpringParams {
+  /** 1 settles without overshoot; lower values bounce, higher values approach more slowly. */
+  dampingRatio: number;
+  stiffness: number;
+}
+export interface SpringState {
+  value: number;
+  /** Units per second. */
+  velocity: number;
+}
+/**
+ * Where a spring is `t` seconds after it starts at `from` with `velocity`, heading to `to`.
+ */
+export declare function solveSpring({ dampingRatio: zeta, stiffness }: SpringParams, from: number, to: number, velocity: number, t: number): SpringState;
+export interface SpringOptions {
+  /** Starting value. */
+  value: number;
+  /** Called on every frame while moving, and once more with the exact target at rest. */
+  onUpdate: (value: number) => void;
+  /** Called when the spring comes to rest. */
+  onRest?: () => void;
+  /**
+   * The spring is at rest when it is within this distance of the target and slower than ten times
+   * this per second. Defaults to 0.01, which suits pixel values.
+   */
+  precision?: number;
+}
+export interface Spring {
+  readonly value: number;
+  readonly velocity: number;
+  readonly target: number;
+  readonly moving: boolean;
+  /**
+   * Heads to a new target from the current position. It keeps the current velocity unless one is
+   * given, for example the speed of a finger at the end of a drag.
+   */
+  to(target: number, params: SpringParams, velocity?: number): void;
+  /** Moves to a value at once, without animating. */
+  jump(value: number): void;
+  /** Stops where it is. */
+  stop(): void;
+}
+/** A spring that animates a single number with `requestAnimationFrame`. */
+export declare function createSpring(options: SpringOptions): Spring;
+/**
+ * Reads a motion token's spring from CSS variables on an element, for example
+ * `--rio-motion-fast-spatial-damping` and `-stiffness`. Reading them from the element, rather than
+ * from the tokens package, lets a subtree that swaps motion schemes change its springs too.
+ * Returns `undefined` when the theme doesn't define them.
+ */
+export declare function readSpringParams(element: Element, token: string): SpringParams | undefined;
+export interface SwitchHandleOptions {
+  /** Returns whether the switch is on. */
+  selected: () => boolean;
+  /** Called when a drag ends on the other side. */
+  onSelectedChange: (selected: boolean) => void;
+}
+export interface SwitchHandleHandle {
+  detach(): void;
+}
+export declare function attachSwitchHandle(root: HTMLElement, options: SwitchHandleOptions): SwitchHandleHandle;
+export interface SwitchProps {
+  /** Whether the switch is on. */
+  selected?: boolean;
+  /** Native disabled: not focusable and not pressable. This is the spec's behavior. */
+  disabled?: boolean;
+  /**
+   * Disabled but still focusable, so it stays discoverable. Presses and drags are blocked in
+   * JavaScript instead. This deviates from the spec, which says disabled components can't be
+   * focused.
+   */
+  softDisabled?: boolean;
+}
+export declare const switchDefaults: {
+  selected: false;
+  disabled: false;
+  softDisabled: false;
+};
+export interface SwitchOptions {
+  /** Returns the current prop values. The adapter owns the state. */
+  props: () => SwitchProps;
+  /** Called with the requested value. Adapters wire it to v-model, onChange, and so on. */
+  onSelectedChange: (selected: boolean) => void;
+}
+export interface SwitchApi {
+  rootAttrs: () => Record<string, string | undefined>;
+  /** Attach to the root element's `click`. */
+  handleClick: (event: MouseEvent) => void;
+}
+export declare function createSwitch(options: SwitchOptions): SwitchApi;

package/dist/index.js

@@ -0,0 +1,605 @@
+// src/button/button.ts
+const BUTTON_VARIANTS = [
+	"filled",
+	"tonal",
+	"outlined",
+	"elevated",
+	"text"
+];
+/** M3E button sizes. `small` is the default. */
+const BUTTON_SIZES = [
+	"xsmall",
+	"small",
+	"medium",
+	"large",
+	"xlarge"
+];
+const buttonDefaults = {
+	variant: "filled",
+	size: "small",
+	shape: "round",
+	toggle: false,
+	selected: false,
+	disabled: false,
+	softDisabled: false,
+	type: "button"
+};
+const isToggle = (p) => !!p.toggle && p.variant !== "text";
+/** Defaults under the given props, skipping props that are explicitly `undefined`. */
+const resolve = (props) => ({
+	...buttonDefaults,
+	...Object.fromEntries(Object.entries(props).filter(([, v]) => v !== void 0))
+});
+function createButton(options) {
+	return {
+		rootAttrs() {
+			const p = resolve(options.props());
+			const toggle = isToggle(p);
+			return {
+				type: p.type,
+				disabled: p.disabled ? "" : void 0,
+				"aria-disabled": p.softDisabled && !p.disabled ? "true" : void 0,
+				"aria-pressed": toggle ? String(p.selected) : void 0,
+				"data-variant": p.variant,
+				"data-size": p.size,
+				"data-shape": p.shape,
+				"data-selected": toggle ? String(p.selected) : void 0
+			};
+		},
+		handleClick(event) {
+			const p = options.props();
+			if (p.disabled || p.softDisabled) {
+				event.preventDefault();
+				return;
+			}
+			options.onClick(event);
+			if (isToggle(p)) options.onSelectedChange(!p.selected);
+		}
+	};
+}
+// src/icon-button/icon-button.ts
+const ICON_BUTTON_VARIANTS = [
+	"filled",
+	"tonal",
+	"outlined",
+	"standard"
+];
+/** M3E icon button widths. `default` makes a square (or circle) as wide as it is tall. */
+const ICON_BUTTON_WIDTHS = [
+	"narrow",
+	"default",
+	"wide"
+];
+const iconButtonDefaults = {
+	variant: "filled",
+	size: "small",
+	width: "default",
+	shape: "round",
+	toggle: false,
+	selected: false,
+	disabled: false,
+	softDisabled: false,
+	type: "button"
+};
+function createIconButton(options) {
+	const button = createButton({
+		...options,
+		props: () => ({
+			...options.props(),
+			variant: options.props().variant
+		})
+	});
+	return {
+		rootAttrs() {
+			const p = options.props();
+			return {
+				...button.rootAttrs(),
+				"aria-label": p.label,
+				"data-width": p.width ?? iconButtonDefaults.width,
+				"data-variant": p.variant ?? iconButtonDefaults.variant
+			};
+		},
+		handleClick: button.handleClick
+	};
+}
+// src/primitives/drag/drag.ts
+/** Velocity is measured over this window, so a pause before release reads as slow. */
+const VELOCITY_WINDOW_MS = 100;
+/** How long to wait for the click that follows a drag before giving up on swallowing it. */
+const CLICK_WINDOW_MS = 400;
+const isDisabled$1 = (el) => el.matches(":disabled, [aria-disabled=\"true\"]");
+function attachDrag(element, options) {
+	const pointerTypes = options.pointerTypes ?? ["touch", "pen"];
+	const threshold = options.threshold ?? 8;
+	let pointerId;
+	let start = {
+		x: 0,
+		y: 0
+	};
+	let samples = [];
+	let dragging = false;
+	const info = (event) => {
+		const first = samples[0];
+		const last = samples.at(-1);
+		const seconds = first && last ? (last.t - first.t) / 1e3 : 0;
+		return {
+			dx: event.clientX - start.x,
+			dy: event.clientY - start.y,
+			velocityX: seconds > 0 ? (last.x - first.x) / seconds : 0,
+			velocityY: seconds > 0 ? (last.y - first.y) / seconds : 0
+		};
+	};
+	const record = (event) => {
+		samples.push({
+			t: event.timeStamp,
+			x: event.clientX,
+			y: event.clientY
+		});
+		samples = samples.filter((s) => event.timeStamp - s.t <= VELOCITY_WINDOW_MS);
+	};
+	const reset = () => {
+		pointerId = void 0;
+		samples = [];
+		dragging = false;
+		delete element.dataset.dragging;
+	};
+	const swallowNextClick = () => {
+		const swallow = (event) => {
+			event.preventDefault();
+			event.stopImmediatePropagation();
+		};
+		element.addEventListener("click", swallow, {
+			capture: true,
+			once: true
+		});
+		setTimeout(() => element.removeEventListener("click", swallow, { capture: true }), CLICK_WINDOW_MS);
+	};
+	const onPointerDown = (event) => {
+		if (!event.isPrimary || !pointerTypes.includes(event.pointerType) || isDisabled$1(element)) return;
+		pointerId = event.pointerId;
+		start = {
+			x: event.clientX,
+			y: event.clientY
+		};
+		samples = [];
+		record(event);
+	};
+	const onPointerMove = (event) => {
+		if (event.pointerId !== pointerId) return;
+		record(event);
+		if (!dragging) {
+			const { dx, dy } = info(event);
+			if (Math.hypot(dx, dy) < threshold) return;
+			dragging = true;
+			try {
+				element.setPointerCapture(event.pointerId);
+			} catch {}
+			element.dataset.dragging = "";
+			options.onStart?.();
+		}
+		options.onMove(info(event));
+	};
+	const onPointerUp = (event) => {
+		if (event.pointerId !== pointerId) return;
+		if (dragging) {
+			record(event);
+			options.onEnd(info(event));
+			swallowNextClick();
+		}
+		reset();
+	};
+	const onPointerCancel = (event) => {
+		if (event.pointerId !== pointerId) return;
+		if (dragging) (options.onCancel ?? options.onEnd)(info(event));
+		reset();
+	};
+	element.addEventListener("pointerdown", onPointerDown);
+	element.addEventListener("pointermove", onPointerMove);
+	element.addEventListener("pointerup", onPointerUp);
+	element.addEventListener("pointercancel", onPointerCancel);
+	return { detach() {
+		reset();
+		element.removeEventListener("pointerdown", onPointerDown);
+		element.removeEventListener("pointermove", onPointerMove);
+		element.removeEventListener("pointerup", onPointerUp);
+		element.removeEventListener("pointercancel", onPointerCancel);
+	} };
+}
+// src/primitives/ripple/ripple.ts
+/** Touch presses wait this long, so a scroll that starts on the element doesn't ripple. */
+const TOUCH_DELAY_MS = 150;
+/** A press stays visible at least this long, even for a quick tap. */
+const MINIMUM_PRESS_MS = 225;
+const GROW_MS = 450;
+/** M3's legacy "standard" easing, which Material Web's ripple uses. */
+const GROW_EASING = "cubic-bezier(0.2, 0, 0, 1)";
+/** The ripple starts at this fraction of the element's larger side. */
+const INITIAL_SCALE = .2;
+const PADDING = 10;
+const SOFT_EDGE_RATIO = .35;
+const SOFT_EDGE_MINIMUM = 75;
+const isDisabled = (el) => el.matches(":disabled, [aria-disabled=\"true\"]");
+const reducedMotion$1 = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+const setPressed = (els, pressed) => {
+	for (const el of els) if (pressed) el.dataset.pressed = "";
+	else delete el.dataset.pressed;
+};
+/**
+* Adds a press ripple to an element. While pressed, the element (and its surface) has
+* `data-pressed`. Load `@rio-m3e/styles/base/ripple.css` for the visuals; it styles elements
+* marked `data-ripple`.
+*/
+function attachRipple(element, options = {}) {
+	const surface = options.surface ?? element;
+	const marked = surface === element ? [element] : [element, surface];
+	let pointerId;
+	let touchTimer;
+	let releaseTimer;
+	let animation;
+	let pressedAt = 0;
+	const start = (event) => {
+		const { width, height, left, top } = surface.getBoundingClientRect();
+		const larger = Math.max(width, height);
+		const softEdge = Math.max(SOFT_EDGE_RATIO * larger, SOFT_EDGE_MINIMUM);
+		const from = event ? {
+			x: event.clientX - left,
+			y: event.clientY - top
+		} : {
+			x: width / 2,
+			y: height / 2
+		};
+		const to = {
+			x: width / 2,
+			y: height / 2
+		};
+		const radius = {
+			from: larger * INITIAL_SCALE / 2,
+			to: (Math.hypot(width, height) + PADDING + softEdge) / 2
+		};
+		const frame = (point, r) => ({
+			"--rio-ripple-x": `${point.x}px`,
+			"--rio-ripple-y": `${point.y}px`,
+			"--rio-ripple-radius": `${r}px`
+		});
+		animation?.cancel();
+		animation = surface.animate([frame(from, radius.from), frame(to, radius.to)], {
+			pseudoElement: "::after",
+			duration: reducedMotion$1() ? 0 : GROW_MS,
+			easing: GROW_EASING,
+			fill: "forwards"
+		});
+		pressedAt = performance.now();
+		setPressed(marked, true);
+	};
+	const end = () => {
+		pointerId = void 0;
+		clearTimeout(touchTimer);
+		touchTimer = void 0;
+		if (!("pressed" in element.dataset)) return;
+		const current = animation;
+		const remaining = MINIMUM_PRESS_MS - (performance.now() - pressedAt);
+		const release = () => {
+			if (animation === current) setPressed(marked, false);
+		};
+		if (remaining > 0) releaseTimer = setTimeout(release, remaining);
+		else release();
+	};
+	const isOwnPointer = (event) => event.isPrimary && (pointerId === void 0 || pointerId === event.pointerId);
+	const onPointerDown = (event) => {
+		if (isDisabled(element) || !event.isPrimary) return;
+		const touch = event.pointerType === "touch";
+		if (!touch && event.buttons !== 1) return;
+		pointerId = event.pointerId;
+		if (!touch) {
+			start(event);
+			return;
+		}
+		touchTimer = setTimeout(() => {
+			touchTimer = void 0;
+			start(event);
+		}, TOUCH_DELAY_MS);
+	};
+	const onPointerUp = (event) => {
+		if (!isOwnPointer(event) || pointerId === void 0) return;
+		if (touchTimer !== void 0) start(event);
+		end();
+	};
+	const onPointerLeave = (event) => {
+		if (event.pointerType !== "touch" && isOwnPointer(event)) end();
+	};
+	const onCancel = (event) => {
+		if (event instanceof PointerEvent && !isOwnPointer(event)) return;
+		end();
+	};
+	const onClick = (event) => {
+		if (event.detail !== 0 || isDisabled(element)) return;
+		start();
+		end();
+	};
+	surface.dataset.ripple = "";
+	element.addEventListener("pointerdown", onPointerDown);
+	element.addEventListener("pointerup", onPointerUp);
+	element.addEventListener("pointerleave", onPointerLeave);
+	element.addEventListener("pointercancel", onCancel);
+	element.addEventListener("contextmenu", onCancel);
+	element.addEventListener("click", onClick);
+	return { detach() {
+		clearTimeout(touchTimer);
+		clearTimeout(releaseTimer);
+		animation?.cancel();
+		delete surface.dataset.ripple;
+		setPressed(marked, false);
+		element.removeEventListener("pointerdown", onPointerDown);
+		element.removeEventListener("pointerup", onPointerUp);
+		element.removeEventListener("pointerleave", onPointerLeave);
+		element.removeEventListener("pointercancel", onCancel);
+		element.removeEventListener("contextmenu", onCancel);
+		element.removeEventListener("click", onClick);
+	} };
+}
+// src/primitives/spring/spring.ts
+/**
+* Where a spring is `t` seconds after it starts at `from` with `velocity`, heading to `to`.
+*/
+function solveSpring({ dampingRatio: zeta, stiffness }, from, to, velocity, t) {
+	const w0 = Math.sqrt(stiffness);
+	const x0 = from - to;
+	const v0 = velocity;
+	if (Math.abs(zeta - 1) < 1e-6) {
+		const b = v0 + w0 * x0;
+		const decay = Math.exp(-w0 * t);
+		return {
+			value: to + (x0 + b * t) * decay,
+			velocity: (b - w0 * (x0 + b * t)) * decay
+		};
+	}
+	if (zeta < 1) {
+		const a = zeta * w0;
+		const wd = w0 * Math.sqrt(1 - zeta * zeta);
+		const b = (v0 + a * x0) / wd;
+		const decay = Math.exp(-a * t);
+		const cos = Math.cos(wd * t);
+		const sin = Math.sin(wd * t);
+		return {
+			value: to + decay * (x0 * cos + b * sin),
+			velocity: decay * ((wd * b - a * x0) * cos - (a * b + wd * x0) * sin)
+		};
+	}
+	const root = w0 * Math.sqrt(zeta * zeta - 1);
+	const r1 = -zeta * w0 + root;
+	const r2 = -zeta * w0 - root;
+	const c2 = (v0 - r1 * x0) / (r2 - r1);
+	const c1 = x0 - c2;
+	const e1 = Math.exp(r1 * t);
+	const e2 = Math.exp(r2 * t);
+	return {
+		value: to + c1 * e1 + c2 * e2,
+		velocity: r1 * c1 * e1 + r2 * c2 * e2
+	};
+}
+const now = () => performance.now() / 1e3;
+/** A spring that animates a single number with `requestAnimationFrame`. */
+function createSpring(options) {
+	const precision = options.precision ?? .01;
+	let from = options.value;
+	let target = options.value;
+	let startVelocity = 0;
+	let params;
+	let startedAt = 0;
+	let frame;
+	const state = () => params && frame !== void 0 ? solveSpring(params, from, target, startVelocity, now() - startedAt) : {
+		value: target,
+		velocity: 0
+	};
+	const settle = () => {
+		if (frame !== void 0) cancelAnimationFrame(frame);
+		frame = void 0;
+		from = target;
+		startVelocity = 0;
+		options.onUpdate(target);
+		options.onRest?.();
+	};
+	const tick = () => {
+		const { value, velocity } = state();
+		if (Math.abs(value - target) < precision && Math.abs(velocity) < precision * 10) {
+			settle();
+			return;
+		}
+		options.onUpdate(value);
+		frame = requestAnimationFrame(tick);
+	};
+	return {
+		get value() {
+			return state().value;
+		},
+		get velocity() {
+			return state().velocity;
+		},
+		get target() {
+			return target;
+		},
+		get moving() {
+			return frame !== void 0;
+		},
+		to(next, nextParams, velocity) {
+			const current = state();
+			from = current.value;
+			startVelocity = velocity ?? current.velocity;
+			target = next;
+			params = nextParams;
+			startedAt = now();
+			if (frame === void 0) frame = requestAnimationFrame(tick);
+		},
+		jump(value) {
+			target = value;
+			settle();
+		},
+		stop() {
+			const { value } = state();
+			if (frame !== void 0) cancelAnimationFrame(frame);
+			frame = void 0;
+			from = target = value;
+			startVelocity = 0;
+		}
+	};
+}
+/**
+* Reads a motion token's spring from CSS variables on an element, for example
+* `--rio-motion-fast-spatial-damping` and `-stiffness`. Reading them from the element, rather than
+* from the tokens package, lets a subtree that swaps motion schemes change its springs too.
+* Returns `undefined` when the theme doesn't define them.
+*/
+function readSpringParams(element, token) {
+	const style = getComputedStyle(element);
+	const dampingRatio = parseFloat(style.getPropertyValue(`--rio-motion-${token}-damping`));
+	const stiffness = parseFloat(style.getPropertyValue(`--rio-motion-${token}-stiffness`));
+	return Number.isFinite(dampingRatio) && Number.isFinite(stiffness) ? {
+		dampingRatio,
+		stiffness
+	} : void 0;
+}
+// src/primitives/spring-property/spring-property.ts
+/** The data attributes Rio's components use for state. */
+const STATE_ATTRIBUTES = [
+	"data-pressed",
+	"data-dragging",
+	"data-selected",
+	"data-shape",
+	"data-size",
+	"data-icon"
+];
+const reducedMotion = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+function attachSpringProperty(element, options) {
+	const token = options.token ?? "fast-spatial";
+	const read = () => parseFloat(getComputedStyle(element).getPropertyValue(options.target));
+	const initial = read();
+	let held = false;
+	const spring = createSpring({
+		value: Number.isFinite(initial) ? initial : 0,
+		onUpdate: (value) => options.apply(value),
+		onRest: () => {
+			if (!held) options.apply(void 0);
+		}
+	});
+	const go = (velocity) => {
+		const target = read();
+		if (!Number.isFinite(target)) return;
+		const params = readSpringParams(element, token);
+		if (!params || reducedMotion()) spring.jump(target);
+		else spring.to(target, params, velocity);
+	};
+	const observer = new MutationObserver(() => {
+		if (!held && read() !== spring.target) go();
+	});
+	observer.observe(element, {
+		attributes: true,
+		attributeFilter: options.watch ?? STATE_ATTRIBUTES
+	});
+	return {
+		get value() {
+			return spring.value;
+		},
+		hold(value) {
+			held = true;
+			spring.jump(value);
+		},
+		release(velocity = 0) {
+			held = false;
+			go(velocity);
+		},
+		detach() {
+			observer.disconnect();
+			spring.stop();
+			options.apply(void 0);
+		}
+	};
+}
+// src/primitives/shape-morph/shape-morph.ts
+function attachShapeMorph(element, options = {}) {
+	const radius = attachSpringProperty(element, {
+		...options,
+		target: "--rio-shape-morph-target",
+		apply: (value) => value === void 0 ? element.style.removeProperty("border-radius") : element.style.setProperty("border-radius", `${value}px`)
+	});
+	element.dataset.shapeMorph = "";
+	return { detach() {
+		radius.detach();
+		delete element.dataset.shapeMorph;
+	} };
+}
+// src/switch/handle.ts
+/** A release faster than this (px/s) picks the side it's heading to, wherever the handle is. */
+const FLING_VELOCITY = 300;
+const inlineVar = (el, name) => (value) => value === void 0 ? el.style.removeProperty(name) : el.style.setProperty(name, `${value}px`);
+const readPx = (el, name) => parseFloat(getComputedStyle(el).getPropertyValue(name));
+function attachSwitchHandle(root, options) {
+	const x = attachSpringProperty(root, {
+		target: "--rio-switch-handle-x-target",
+		apply: inlineVar(root, "--_handle-x")
+	});
+	const size = attachSpringProperty(root, {
+		target: "--rio-switch-handle-size-target",
+		apply: inlineVar(root, "--_handle-size")
+	});
+	let from = 0;
+	let off = 0;
+	let on = 0;
+	let direction = 1;
+	const drag = attachDrag(root, {
+		onStart() {
+			off = readPx(root, "--rio-switch-handle-x-off");
+			on = readPx(root, "--rio-switch-handle-x-on");
+			direction = getComputedStyle(root).direction === "rtl" ? -1 : 1;
+			from = x.value;
+			x.hold(from);
+		},
+		onMove({ dx }) {
+			x.hold(Math.min(on, Math.max(off, from + direction * dx)));
+		},
+		onEnd({ velocityX }) {
+			const velocity = direction * velocityX;
+			const next = Math.abs(velocity) > FLING_VELOCITY ? velocity > 0 : x.value > (off + on) / 2;
+			if (next !== options.selected()) options.onSelectedChange(next);
+			x.release(velocity);
+		},
+		onCancel() {
+			x.release();
+		}
+	});
+	return { detach() {
+		drag.detach();
+		x.detach();
+		size.detach();
+	} };
+}
+// src/switch/switch.ts
+const switchDefaults = {
+	selected: false,
+	disabled: false,
+	softDisabled: false
+};
+function createSwitch(options) {
+	return {
+		rootAttrs() {
+			const p = options.props();
+			const selected = String(!!p.selected);
+			return {
+				type: "button",
+				role: "switch",
+				"aria-checked": selected,
+				disabled: p.disabled ? "" : void 0,
+				"aria-disabled": p.softDisabled && !p.disabled ? "true" : void 0,
+				"data-selected": selected
+			};
+		},
+		handleClick(event) {
+			const p = options.props();
+			if (p.disabled || p.softDisabled) {
+				event.preventDefault();
+				return;
+			}
+			options.onSelectedChange(!p.selected);
+		}
+	};
+}
+export { BUTTON_SIZES, BUTTON_VARIANTS, ICON_BUTTON_VARIANTS, ICON_BUTTON_WIDTHS, STATE_ATTRIBUTES, attachDrag, attachRipple, attachShapeMorph, attachSpringProperty, attachSwitchHandle, buttonDefaults, createButton, createIconButton, createSpring, createSwitch, iconButtonDefaults, readSpringParams, solveSpring, switchDefaults };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@rio-m3e/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Framework-agnostic state, props and behaviors for Rio",
+  "license": "Apache-2.0",
+  "author": "LegenLee",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LegenLee/rio.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@rio-m3e/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsdown": "0.23.7",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p ."
+  }
 }