@wardic/solid 0.0.0-stage → 1.0.0-rc.1

package/src/wardic-config-value.ts

@@ -0,0 +1,150 @@
+/**
+ * What a `WardicConfig` gives the Wardic elements below it (#434, Motion's `MotionConfig`),
+ * Solid-free, on both bindings: its **Config transition**, its reduced motion and whether its
+ * animations are skipped (#468).
+ *
+ * - **The Config transition is an element's own when it gives none,** as Motion's
+ *   `{ ...config, ...props }`: whatever reads the element's `transition` reads it, a Variant child's in
+ *   place of its parent's (Q3).
+ * - **Its reduced motion** (ADR-0029) is the element's, over the `WardicProvider`'s (Q2), as Motion
+ *   reads its `MotionConfig`'s per element.
+ * - **`skipAnimations`** (#468) makes every animation of the elements below a **Skipped animation**,
+ *   Motion's `MotionConfig` `skipAnimations`, whatever their reduced motion.
+ * - **`isValidProp`** (#443) keeps a tag's props it says aren't valid off its element, Motion's
+ *   `MotionConfig` `isValidProp`.
+ * - **`transformPagePoint`** (#443) maps the points a drag or a pan below it uses, Motion's
+ *   `MotionConfig` `transformPagePoint`.
+ * - **A `WardicConfig` inside another** replaces its transition, or with `inherit: true` lays its own
+ *   fields over it (Motion's `resolveTransition`); one that gives none passes its parent's on, as one
+ *   that gives no reduced motion, `skipAnimations`, `isValidProp` or `transformPagePoint` passes its parent's.
+ *
+ * @module
+ */
+import type * as ReducedMotion from "@wardic/core/ReducedMotion"
+import { constFalse, constUndefined } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import type { WardicTransformPoint, WardicTransition, WardicVariantTransition } from "./config.ts"
+import { transitionOfTarget } from "./variant-target.ts"
+
+/** What a `WardicConfig` gives below it (#434): one value per config, read where a binding reads it. */
+export interface WardicConfigValue {
+  /** Its **Config transition**: read when an element's transition is, so a change starts nothing by itself. */
+  readonly transition: () => WardicTransition | undefined
+  /**
+   * Its reduced motion (ADR-0029): its own, else an enclosing config's, else `undefined` for the
+   * `WardicProvider`'s. Read when each animation starts.
+   */
+  readonly reducedMotion: () => ReducedMotion.Config | undefined
+  /**
+   * Whether its animations are skipped (#468): its own, else an enclosing config's, else `undefined`,
+   * as `false`. Read when each animation starts.
+   */
+  readonly skipAnimations: () => boolean | undefined
+  /**
+   * Which of a tag's own props reach its element (#443, Motion's `MotionConfig` `isValidProp`): its
+   * own, else an enclosing config's, else `undefined`, every one. Read as each element is made.
+   */
+  readonly isValidProp: () => ((key: string) => boolean) | undefined
+  /**
+   * Where a drag's or a pan's points are (#443, Motion's `MotionConfig` `transformPagePoint`): its
+   * own, else an enclosing config's, else `undefined`, as they are. Read at each drag or pan start.
+   */
+  readonly transformPagePoint: () => WardicTransformPoint | undefined
+}
+
+/**
+ * A `WardicConfig`'s transition (#434): its own, laid over its parent's with `inherit: true` (as a
+ * variant's own is over the element's), else its parent's when it gives none.
+ */
+export const configTransitionOf = (own: WardicVariantTransition | undefined, parent: WardicConfigValue | undefined): WardicTransition | undefined =>
+  transitionOfTarget(own, parentTransitionOf(parent))
+
+const parentTransitionOf = (parent: WardicConfigValue | undefined): WardicTransition | undefined => {
+  if (Predicate.isUndefined(parent)) return undefined
+  return parent.transition()
+}
+
+/** A `WardicConfig`'s reduced motion (#434): its own, else its parent's, else none (the provider's). */
+export const configReducedMotionOf = (own: ReducedMotion.Config | undefined, parent: WardicConfigValue | undefined): ReducedMotion.Config | undefined => {
+  if (Predicate.isNotUndefined(own)) return own
+  if (Predicate.isUndefined(parent)) return undefined
+  return parent.reducedMotion()
+}
+
+/** A `WardicConfig`'s `skipAnimations` (#468): its own, else its parent's, else none. */
+export const configSkipAnimationsOf = (own: boolean | undefined, parent: WardicConfigValue | undefined): boolean | undefined => {
+  if (Predicate.isNotUndefined(own)) return own
+  if (Predicate.isUndefined(parent)) return undefined
+  return parent.skipAnimations()
+}
+
+/** A `WardicConfig`'s `isValidProp` (#443): its own, else its parent's, else none. */
+export const configIsValidPropOf = (own: ((key: string) => boolean) | undefined, parent: WardicConfigValue | undefined): ((key: string) => boolean) | undefined => {
+  if (Predicate.isNotUndefined(own)) return own
+  if (Predicate.isUndefined(parent)) return undefined
+  return parent.isValidProp()
+}
+
+/** A `WardicConfig`'s `transformPagePoint` (#443): its own, else its parent's, else none. */
+export const configTransformPagePointOf = (own: WardicTransformPoint | undefined, parent: WardicConfigValue | undefined): WardicTransformPoint | undefined => {
+  if (Predicate.isNotUndefined(own)) return own
+  if (Predicate.isUndefined(parent)) return undefined
+  return parent.transformPagePoint()
+}
+
+/** The nearest config's `transformPagePoint` (#443), read at each drag or pan start: `undefined` for none. */
+export const transformPagePointOf = (config: WardicConfigValue | undefined): (() => WardicTransformPoint | undefined) => {
+  if (Predicate.isUndefined(config)) return constUndefined
+  return () => config.transformPagePoint()
+}
+
+/**
+ * A `transformPagePoint` as core's gestures take it (#618, A1): an `Option`, the same `Some` while the
+ * mapping is the same, so a gesture's down allocates nothing.
+ */
+export const pointMapOptionOf = (read: () => WardicTransformPoint | undefined): (() => Option.Option<WardicTransformPoint>) => {
+  let last: Option.Option<WardicTransformPoint> = Option.none()
+  return () => {
+    const now = read()
+    if (Predicate.isUndefined(now)) return Option.none()
+    if (Option.isSome(last)) {
+      if (last.value === now) return last
+    }
+    last = Option.some(now)
+    return last
+  }
+}
+
+/** The nearest config's `isValidProp` (#443), as an element is made: `undefined` for none. */
+export const isValidPropOf = (config: WardicConfigValue | undefined): ((key: string) => boolean) | undefined => {
+  if (Predicate.isUndefined(config)) return undefined
+  return config.isValidProp()
+}
+
+/**
+ * Whether an element's animations are skipped (#468), read when each starts: its nearest config's
+ * `skipAnimations`. With no config above, never, and nothing made.
+ */
+export const skipAnimationsOf = (config: WardicConfigValue | undefined): (() => boolean) => {
+  if (Predicate.isUndefined(config)) return constFalse
+  return () => config.skipAnimations() === true
+}
+
+/** The reduced motion an element's nearest config sets (#434), now: `undefined` for none, the provider's. */
+export const settingOf = (config: WardicConfigValue | undefined): ReducedMotion.Config | undefined => {
+  if (Predicate.isUndefined(config)) return undefined
+  return config.reducedMotion()
+}
+
+/**
+ * `c` with its **Config transition** as its own when it gives none (#434, Motion's spread): `c` as it
+ * is when it has its own or the config gives none.
+ */
+export const withConfigTransition = <C extends { readonly transition?: WardicTransition | undefined }>(c: C, config: WardicConfigValue | undefined): C => {
+  if (Predicate.isNotUndefined(c.transition)) return c
+  if (Predicate.isUndefined(config)) return c
+  const transition = config.transition()
+  if (Predicate.isUndefined(transition)) return c
+  return { ...c, transition }
+}

package/src/wardic-config.tsx

@@ -0,0 +1,78 @@
+/**
+ * `WardicConfig` on the Solid 1 binding (#434, Motion's `MotionConfig`): settings for the Wardic
+ * elements below it. It provides a context and no runtime, so it nests anywhere under a
+ * `WardicProvider`.
+ *
+ * @module
+ */
+import { createContext, createMemo, type JSX, useContext } from "solid-js"
+import type * as ReducedMotion from "@wardic/core/ReducedMotion"
+import type { WardicTransformPoint, WardicVariantTransition } from "./config.ts"
+import { configIsValidPropOf, configReducedMotionOf, configTransformPagePointOf, configSkipAnimationsOf, configTransitionOf, type WardicConfigValue } from "./wardic-config-value.ts"
+
+const WardicConfigContext = createContext<WardicConfigValue | undefined>(undefined)
+
+/** `WardicConfig`'s props. */
+export interface WardicConfigProps {
+  /**
+   * The **Config transition**: each Wardic element below runs on it when it gives no `transition` of
+   * its own, a Variant child in place of its parent's, as Motion's `MotionConfig` `transition`. It
+   * replaces an enclosing config's, or with `inherit: true` lays its own fields over it. Read when
+   * each animation starts.
+   */
+  readonly transition?: WardicVariantTransition | undefined
+  /**
+   * How the Wardic elements below honour the user's `prefers-reduced-motion`, as Motion's
+   * `MotionConfig` `reducedMotion`: `"user"` follows it, `"always"` reduces motion whatever it is,
+   * `"never"` animates whatever it is. It replaces an enclosing config's, and the `WardicProvider`'s
+   * for them; with none, theirs applies. Read when each animation starts.
+   */
+  readonly reducedMotion?: ReducedMotion.Config | undefined
+  /**
+   * Every animation of the Wardic elements below lands at its end on the next frame, as Motion's
+   * `MotionConfig` `skipAnimations`: its legs, exits, layout animations, a drag's release,
+   * `createAnimate` and `createSpring`, each still told. For end-to-end and visual-regression tests.
+   * An inner config's `false` animates its subtree again. Read when each animation starts.
+   */
+  readonly skipAnimations?: boolean | undefined
+  /**
+   * Which of the props given a Wardic element's tag below reach the element (Motion's
+   * `MotionConfig` `isValidProp`): one it returns `false` for is kept off it, for a prop a styling
+   * system reads that shouldn't render as an attribute. Asked of no prop starting with `on`, nor a
+   * wrapped component's, which get every prop, as Motion's do. It replaces an enclosing config's. Read as
+   * each element is made, for the props it has then.
+   */
+  readonly isValidProp?: ((key: string) => boolean) | undefined
+  /**
+   * Where the points a drag or a pan below uses are (Motion's `MotionConfig`
+   * `transformPagePoint`): handed each point in the viewport's coordinates, it gives the one the
+   * gesture uses. Read at each drag or pan start, and applied to its down, each move, a drag
+   * controls' start and its snap to the cursor, and to the boxes drag constraints are measured from;
+   * never to a layout animation's boxes, which Wardic already reads through their ancestors'
+   * transforms. `correctParentTransform(parent)` makes one for a zoomed or rotated parent, and
+   * `transformViewBoxPoint(svg)` one for an SVG's viewBox. It replaces an enclosing config's.
+   */
+  readonly transformPagePoint?: WardicTransformPoint | undefined
+  readonly children?: JSX.Element
+}
+
+/**
+ * Settings for the Wardic elements below it (Motion's `MotionConfig`): their default
+ * `transition`, their `reducedMotion` and `skipAnimations`. Nest it anywhere under a
+ * `WardicProvider`; an inner one replaces an outer one's, unless its transition inherits it.
+ *
+ * ```tsx
+ * <WardicConfig transition={{ type: "spring", stiffness: 300, damping: 30 }}>
+ *   <wardic.div animate={{ x: 100 }} />
+ * </WardicConfig>
+ * ```
+ */
+export function WardicConfig(props: WardicConfigProps): JSX.Element {
+  const parent = useContext(WardicConfigContext)
+  // One object per change, so the elements below share it, and its caches (#66, #301) hit.
+  const transition = createMemo(() => configTransitionOf(props.transition, parent))
+  return <WardicConfigContext.Provider value={{ transition, reducedMotion: () => configReducedMotionOf(props.reducedMotion, parent), skipAnimations: () => configSkipAnimationsOf(props.skipAnimations, parent), isValidProp: () => configIsValidPropOf(props.isValidProp, parent), transformPagePoint: () => configTransformPagePointOf(props.transformPagePoint, parent) }}>{props.children}</WardicConfigContext.Provider>
+}
+
+/** The nearest `WardicConfig`'s settings, or none. Internal. */
+export const useWardicConfig = (): WardicConfigValue | undefined => useContext(WardicConfigContext)

package/src/wardic.tsx

@@ -0,0 +1,59 @@
+/**
+ * `wardic.create(tag | Component)` HOC + the `wardic.*` motion-element proxy (ADR-0008,
+ * Tier 1 headline surface): the **Complete element**'s component forms, every Feature brought with it
+ * (#511, ADR-0067), as Motion's `motion` is. The forms' shared code, and how a component is made, is
+ * `element.tsx`'s; `w.tsx` holds the Slim element's forms.
+ *
+ * `wardic.<tag>` (e.g. `wardic.div`, `wardic.button`) is a cached shorthand for
+ * `wardic.create("<tag>")` — `wardic.div === wardic.div`.
+ *
+ * `wardic.create`'s options (#443, Motion's): `forwardMotionProps` hands the motion props on too, and
+ * `type` says what its element is for its server render. Every component made is marked
+ * (`isWardicComponent`), and a `WardicConfig`'s `isValidProp` keeps a tag's props off its element.
+ */
+import type { Accessor, JSX } from "solid-js"
+import { runDirective } from "./directive.ts"
+import { COMPLETE } from "./complete.ts"
+import type { WardConfig } from "./config.ts"
+import { type Create, createOf, formOf, type WardicComponent } from "./element.tsx"
+
+export { MOTION_PROPS, motionToConfig, type WardicMotionProps } from "./motion-props.ts"
+export { configOfMotion, type Create, type WardicComponent, type WardicProps, type WardicWrappable } from "./element.tsx"
+
+/**
+ * `wardic.create(tag | Component)` — build a **Complete element** (#511): the
+ * forms' `create` (`element.tsx`'s `createWith`), bringing every Feature.
+ *
+ * @param arg an element tag string (e.g. `"div"`) OR a component forwarding `ref`.
+ * @returns a Solid component accepting the element's / component's props + motion props.
+ */
+export const create: Create = createOf(COMPLETE)
+
+/**
+ * The `use:wardic` directive: drive `el` through Wardic's motion spine, a Complete element. An arrow
+ * function, so the `wardic` Proxy over it has no non-configurable `prototype` to keep.
+ */
+const wardicDirective = (el: HTMLElement, value: Accessor<WardConfig>): void => runDirective(el, value, COMPLETE)
+
+/**
+ * The typed `wardic` proxy: called, it's the `use:wardic` directive; `wardic.create` is the
+ * HOC, and `wardic.<tag>` is a Complete element for that intrinsic element (cached per tag).
+ */
+export type Wardic = ((el: HTMLElement, value: Accessor<WardConfig>) => void) & {
+  readonly create: typeof create
+} & {
+  readonly [Tag in keyof JSX.IntrinsicElements]: WardicComponent<Tag>
+}
+
+/**
+ * The Complete element: `wardic.div` and every other tag, with every Feature whatever its section
+ * gives, and `wardic.create(Component)`. Handy for trying something out, heavy for a page: under a
+ * `strict` provider it throws in development. Motion's `motion.div`.
+ *
+ * @example <wardic.div drag whileHover={{ scale: 1.05 }} />
+ * @see https://wardic.dev/reference/solid/elements/wardic
+ */
+// The motion-element proxy and the `use:wardic` directive (ADR-0008 Tier 1, ADR-0042): every way to
+// make a Complete Wardic element but createWard's spread. `wardic(el, accessor)` is the directive;
+// `wardic.<tag>` is `create(tag)`, cached so `wardic.div === wardic.div`; any other key is undefined.
+export const wardic: Wardic = formOf<Wardic>(wardicDirective, create, {})