@solidrt/components 0.0.51 → 0.0.53

package/src/theme.ts

@@ -38,6 +38,8 @@ export type Theme = {
   text: {
     // Passed through to the core font stack: "sans" | "mono" | a family name.
     fontFamily: string
+    // The monospace family for code (RichTextEditor inline code).
+    monoFamily: string
     caption: TextStyle
     label: TextStyle
     body: TextStyle
@@ -69,10 +71,24 @@ export type Theme = {
     // caller-set style.backgroundColor. Non-touch interaction policies only.
     overlayHover: string
     overlayPressed: string
+    // The focus ring (spatial nav under the focusRing policy), drawn at
+    // borderWidth.focus by every focusable control. Defaults to text so it
+    // stays visible on primary-filled controls.
+    ring: string
   }
+  // Gaps and paddings, multiples of one base unit (sm 1x, md 2x, lg 4x,
+  // xl 5x); read through space() where density should apply.
   spacing: { sm: number; md: number; lg: number; xl: number }
-  radius: { sm: number; md: number; lg: number }
-  borderWidth: { sm: number }
+  // Corner radii. md is THE control radius (Button, TextInput, Select,
+  // SegmentedControl); sm is one step under it (Checkbox, Item, menus,
+  // Tooltip), lg one step over (Card), full is the pill.
+  radius: { sm: number; md: number; lg: number; full: number }
+  borderWidth: { sm: number; focus: number }
+  // Default extents of the components that have one: the panes and rails an
+  // app lays its screens around, and the smallest sensible popup/track. Each
+  // is a per-instance layout override away (listWidth, layout.width, ...);
+  // the theme sets the app-wide default.
+  size: { navRail: number; navSidebar: number; splitViewList: number; menuMinWidth: number; slider: number }
   // Semantic control glyphs, as SVG document strings (the Icon currency).
   // Components draw their built-in vector paths by default; a theme that sets
   // a slot swaps that glyph everywhere it appears. The package still bundles
@@ -93,9 +109,10 @@ export type Theme = {
 export type ThemeColor = string | [light: string, dark: string]
 
 export type ThemeDefinition = {
-  color: { [K in keyof Theme["color"]]: ThemeColor }
+  color: { [K in Exclude<keyof Theme["color"], "ring">]: ThemeColor } & { ring?: ThemeColor }
   text?: {
     fontFamily?: string
+    monoFamily?: string
     // The body font size; the other roles derive from it. Default 14.
     base?: number
     // The step between adjacent roles (caption, label, body, title, heading
@@ -105,23 +122,43 @@ export type ThemeDefinition = {
     // and weights.
     roles?: { [K in TextVariant]?: Partial<TextStyle> }
   }
-  spacing?: Partial<Theme["spacing"]>
-  radius?: Partial<Theme["radius"]>
+  // One base unit (the steps derive from it, see deriveSpacing) or explicit
+  // steps. Default 4.
+  spacing?: number | Partial<Theme["spacing"]>
+  // One base (the control radius; the steps derive from it, see
+  // deriveRadius) or explicit steps. Default 8.
+  radius?: number | Partial<Theme["radius"]>
   borderWidth?: Partial<Theme["borderWidth"]>
+  size?: Partial<Theme["size"]>
   icons?: Theme["icons"]
   components?: Theme["components"]
 }
 
-const SPACING = { sm: 4, md: 8, lg: 16, xl: 20 }
-const RADIUS = { sm: 4, md: 8, lg: 12 }
-const BORDER_WIDTH = { sm: 1 }
+const SPACING_BASE = 4
 
-// Line height and weight per role; body is the base text, caption and label
-// sit under it (secondary and emphasized small text), title and heading
-// above it (card and page headings).
+// The spacing scale from its base unit.
+function deriveSpacing(base: number): Theme["spacing"] {
+  return { sm: base, md: base * 2, lg: base * 4, xl: base * 5 }
+}
+const RADIUS_BASE = 8
+const RADIUS_FULL = 9999
+
+// The radius scale from its base: sm half, lg one and a half, full the pill.
+function deriveRadius(base: number): Theme["radius"] {
+  return { sm: Math.round(base / 2), md: base, lg: Math.round(base * 1.5), full: RADIUS_FULL }
+}
+const BORDER_WIDTH = { sm: 1, focus: 2 }
+const SIZE = { navRail: 72, navSidebar: 220, splitViewList: 320, menuMinWidth: 120, slider: 200 }
+
+// Line height and weight per role; body is the base text, label is body at
+// an emphasized weight (form labels, key/value keys, tags), caption the one
+// small role (badges, tab labels, timestamps), title and heading sit above
+// body (card and page headings). De-emphasis is a color (textMuted), not a
+// size: caption is small text to be glanced at, so keep it in the full text
+// color rather than stacking small and muted.
 const ROLE_DEFAULTS: { [K in TextVariant]: { step: number; lineHeight: number; weight: TextStyle["weight"] } } = {
-  caption: { step: -2, lineHeight: 1.3, weight: 400 },
-  label: { step: -1, lineHeight: 1.3, weight: 600 },
+  caption: { step: -1, lineHeight: 1.3, weight: 400 },
+  label: { step: 0, lineHeight: 1.5, weight: 600 },
   body: { step: 0, lineHeight: 1.5, weight: 400 },
   title: { step: 1, lineHeight: 1.4, weight: 700 },
   heading: { step: 2, lineHeight: 1.3, weight: 700 },
@@ -139,11 +176,13 @@ export function defineTheme(def: ThemeDefinition, scheme?: "light" | "dark"): Th
   for (let key in def.color) {
     let k = key as keyof Theme["color"]
     let value = def.color[k]
+    if (value == null) continue
     if (Array.isArray(value)) {
       if (!scheme) throw new Error(`Theme color "${key}" is a [light, dark] pair; pass a scheme to defineTheme`)
       color[k] = value[scheme === "light" ? 0 : 1]
     } else color[k] = value
   }
+  if (def.color.ring == null) color.ring = color.text
   let base = def.text?.base ?? 14
   let ratio = def.text?.ratio ?? 1.26
   let role = (name: TextVariant): TextStyle => {
@@ -158,6 +197,7 @@ export function defineTheme(def: ThemeDefinition, scheme?: "light" | "dark"): Th
   return {
     text: {
       fontFamily: def.text?.fontFamily ?? "sans",
+      monoFamily: def.text?.monoFamily ?? "mono",
       caption: role("caption"),
       label: role("label"),
       body: role("body"),
@@ -165,9 +205,14 @@ export function defineTheme(def: ThemeDefinition, scheme?: "light" | "dark"): Th
       heading: role("heading"),
     },
     color,
-    spacing: { ...SPACING, ...def.spacing },
-    radius: { ...RADIUS, ...def.radius },
+    spacing:
+      typeof def.spacing === "number"
+        ? deriveSpacing(def.spacing)
+        : { ...deriveSpacing(SPACING_BASE), ...def.spacing },
+    radius:
+      typeof def.radius === "number" ? deriveRadius(def.radius) : { ...deriveRadius(RADIUS_BASE), ...def.radius },
     borderWidth: { ...BORDER_WIDTH, ...def.borderWidth },
+    size: { ...SIZE, ...def.size },
     icons: def.icons ?? {},
     components: def.components ?? {},
   }
@@ -180,7 +225,10 @@ const DEFAULT: ThemeDefinition = {
     background: ["#ffffff", "#0b0f17"],
     surface: ["#f6f8fa", "#161b22"],
     surfaceAlt: ["#eaeef2", "#21262d"],
-    text: ["#1f2328", "#e6edf3"],
+    // Dark body text sits well under white (about 10:1 on the background,
+    // tuned by eye on a low-DPI display): full brightness glares on a dark
+    // ground, and the low-DPI weight compensation thickens it further.
+    text: ["#1f2328", "#b1bac4"],
     // Muted is an opaque tone between text and background, mixed in oklab
     // (like Material 3's tonal colors, not an alpha overlay): alpha text
     // renders thin on low-DPI and its contrast depends on what sits behind
@@ -188,7 +236,10 @@ const DEFAULT: ThemeDefinition = {
     // preset is data that must not need the render engine at import time
     // (the website token build imports this module headless). If text or
     // background changes, recompute: mixColors(text, background, 0.4).
-    textMuted: ["#707376", "#848b92"],
+    // The dark tone sits a step above the 4.5:1 AA floor (about 5.4:1)
+    // instead of at the mix: the body text already sits low, and the
+    // strict mix falls under it.
+    textMuted: ["#707376", "#828993"],
     border: ["rgba(0,0,0,0.15)", "rgba(255,255,255,0.14)"],
     // Accent tuned to the puzzle mark's mid blue.
     primary: "#547ebf",
@@ -202,9 +253,10 @@ const DEFAULT: ThemeDefinition = {
     overlayHover: ["rgba(0,0,0,0.08)", "rgba(255,255,255,0.08)"],
     overlayPressed: ["rgba(0,0,0,0.14)", "rgba(255,255,255,0.14)"],
   },
-  // base 14 and ratio 1.26 derive title 18 and heading 22; the two small
-  // roles sit tighter than the ratio, so they are pinned.
-  text: { roles: { caption: { size: 11 }, label: { size: 12 } } },
+  // base 14 and ratio 1.26 derive title 18 and heading 22; caption sits
+  // one step under body but the ratio lands on 11, too small to read on a
+  // low-DPI display or at TV distance, so it is pinned.
+  text: { roles: { caption: { size: 12 } } },
 }
 
 export let darkTheme: Theme = defineTheme(DEFAULT, "dark")

package/src/tooltip.tsx

@@ -4,8 +4,10 @@ import { theme } from "./theme"
 import { policy } from "./policy"
 import { space } from "./spacing"
 import { typeStyle } from "./typography"
+import type { TransitionProps } from "./types"
+import { splitTransition, transitionEndFor } from "./types"
 
-export interface TooltipProps {
+export interface TooltipProps extends TransitionProps {
   // The tooltip body. A string/number renders as themed text; anything else
   // renders as-is.
   content?: any
@@ -19,9 +21,10 @@ export interface TooltipProps {
 }
 
 const DELAY = 500
-const GAP = 6
+// Distance between the anchor and the bubble.
+let gap = () => theme.spacing.sm
 // Minimum distance kept between the bubble and the window edges.
-const MARGIN = 4
+let margin = () => theme.spacing.sm
 
 /**
  * A hover-only affordance: under desktop/hybrid interaction policies, resting a
@@ -61,8 +64,8 @@ export function Tooltip(props: TooltipProps) {
       let b = bubble && getBoundingBox(bubble)
       if (!a || !b) return
       let x = a.x + a.width / 2 - b.width / 2
-      x = Math.round(Math.min(Math.max(x, MARGIN), env.windowSize.width - b.width - MARGIN))
-      let y = Math.round(props.placement === "bottom" ? a.y + a.height + GAP : a.y - b.height - GAP)
+      x = Math.round(Math.min(Math.max(x, margin()), env.windowSize.width - b.width - margin()))
+      let y = Math.round(props.placement === "bottom" ? a.y + a.height + gap() : a.y - b.height - gap())
       let cur = pos()
       if (!cur || cur.x !== x || cur.y !== y) setPos({ x, y })
     })
@@ -86,6 +89,8 @@ export function Tooltip(props: TooltipProps) {
         pointerEvents="none"
       >
         <d-rect
+          transition={split().background}
+          onTransitionEnd={transitionEndFor("background", props.onTransitionEnd)}
           color={theme.components.tooltip?.backgroundColor ?? theme.color.surfaceAlt}
           radius={theme.components.tooltip?.borderRadius ?? theme.radius.sm}
         />
@@ -96,6 +101,8 @@ export function Tooltip(props: TooltipProps) {
         </Show>
         <d-rect
           drawStyle="stroke"
+          transition={split().border}
+          onTransitionEnd={transitionEndFor("border", props.onTransitionEnd)}
           color={theme.components.tooltip?.borderColor ?? theme.color.border}
           strokeWidth={theme.components.tooltip?.borderWidth ?? theme.borderWidth.sm}
           radius={theme.components.tooltip?.borderRadius ?? theme.radius.sm}
@@ -104,8 +111,12 @@ export function Tooltip(props: TooltipProps) {
     )
   }
 
+  let split = () => splitTransition(props.transition)
+
   return (
     <view
+      transition={split().root}
+      onTransitionEnd={transitionEndFor("root", props.onTransitionEnd)}
       ref={(n: { id: number }) => (anchor = n)}
       onPointerEnter={enter}
       onPointerLeave={hide}

package/src/types.ts

@@ -1,4 +1,122 @@
-import type { Color, Gradient, LayoutProps } from "@solidrt/core"
+import type {
+  Color,
+  Gradient,
+  LayoutProps,
+  Transition,
+  TransitionEndEvent,
+  TransitionPropName,
+  TransitionProps as CoreTransitionProps,
+} from "@solidrt/core"
+
+// Native transitions through a component. A component is a root view plus
+// the nodes it draws for `style` (a background d-rect, a stroke d-rect for
+// the border), so a declaration names the STYLE properties - backgroundColor,
+// borderColor, borderWidth, borderRadius - next to the view-level ones, and
+// splitTransition hands each entry to the node that owns it. Core's paint
+// names (color, radius, strokeWidth) are deliberately not accepted: on a
+// component they would land on the root view, which has no paint, and be
+// silently ignored.
+//
+// Controls whose paint is their own (Switch knob, Slider thumb, Checkbox
+// mark, ...) take the view-level entries only for now; see
+// okf/backlog/component-transitions-internal-paint.md.
+export type TransitionViewProp =
+  | "opacity"
+  | "x"
+  | "y"
+  | "scale"
+  | "scaleX"
+  | "scaleY"
+  | "rotate"
+  | "rotateX"
+  | "rotateY"
+  | "originX"
+  | "originY"
+  | "perspective"
+  | "clipRadius"
+export type TransitionStyleProp = "backgroundColor" | "borderColor" | "borderWidth" | "borderRadius"
+export type TransitionScrollProp = "scrollX" | "scrollY"
+
+type TransitionEntries<P extends string> = {
+  /** One spec for every property the component animates (no `from`/`exit` here, as in core). */
+  all?: Transition
+  /** Group stagger (ms) for descendant enter/exit animations; see core. */
+  stagger?: number
+} & { [K in P]?: Transition }
+
+/** A component's transition declaration: view-level and style names, `all`, or a shorthand string. */
+export type ComponentTransition<P extends string = TransitionViewProp | TransitionStyleProp> =
+  | TransitionEntries<P>
+  | string
+  | null
+
+export interface TransitionProps<P extends string = TransitionViewProp | TransitionStyleProp> {
+  /**
+   * Animate later writes of the listed properties instead of snapping, like
+   * the core `transition` prop but in the component's own vocabulary:
+   * `transition={{ opacity: "200ms ease-out", backgroundColor: { duration: 300 } }}`.
+   * `all` or a bare string covers every property the component animates.
+   */
+  transition?: ComponentTransition<P>
+  /** A transition settled; `property` is in the component's vocabulary (`backgroundColor`, not `color`). */
+  onTransitionEnd?: (event: { property: P }) => void
+}
+
+/** The core transition declarations for a component's root view and its background/border rects. */
+export type SplitTransition = {
+  root: CoreTransitionProps["transition"]
+  background: CoreTransitionProps["transition"]
+  border: CoreTransitionProps["transition"]
+}
+
+const STYLE_TO_BACKGROUND: Record<string, TransitionPropName> = { backgroundColor: "color", borderRadius: "radius" }
+const STYLE_TO_BORDER: Record<string, TransitionPropName> = {
+  borderColor: "color",
+  borderWidth: "strokeWidth",
+  borderRadius: "radius",
+}
+
+/**
+ * Map a component declaration onto the three nodes a styled component
+ * draws. `all`, a shorthand string and `stagger` apply to every node; named
+ * entries go to the node owning the property. An entry for a node that is
+ * not mounted (no background set) simply never animates.
+ */
+export function splitTransition<P extends string>(t: ComponentTransition<P> | undefined): SplitTransition {
+  if (t == null || typeof t === "string") return { root: t, background: t, border: t }
+  let root: Record<string, unknown> = {}
+  let background: Record<string, unknown> = {}
+  let border: Record<string, unknown> = {}
+  for (let [key, value] of Object.entries(t)) {
+    if (key === "all" || key === "stagger") {
+      root[key] = value
+      background[key] = value
+      border[key] = value
+    } else if (key in STYLE_TO_BACKGROUND || key in STYLE_TO_BORDER) {
+      if (key in STYLE_TO_BACKGROUND) background[STYLE_TO_BACKGROUND[key]!] = value
+      if (key in STYLE_TO_BORDER) border[STYLE_TO_BORDER[key]!] = value
+    } else {
+      root[key] = value
+    }
+  }
+  let pick = (o: Record<string, unknown>) => (Object.keys(o).length ? (o as CoreTransitionProps["transition"]) : undefined)
+  return { root: pick(root), background: pick(background), border: pick(border) }
+}
+
+/** Report a settled core property in the component vocabulary for the node it settled on. */
+export function transitionEndFor<P extends string>(
+  node: "root" | "background" | "border",
+  handler: ((event: { property: P }) => void) | undefined,
+): ((event: TransitionEndEvent) => void) | undefined {
+  if (!handler) return undefined
+  return (e) => {
+    let name: string = e.property
+    if (node === "background") name = e.property === "color" ? "backgroundColor" : "borderRadius"
+    if (node === "border")
+      name = e.property === "color" ? "borderColor" : e.property === "strokeWidth" ? "borderWidth" : "borderRadius"
+    handler({ property: name as P })
+  }
+}
 
 // The split between layout and style follows one rule: layout properties feed
 // into Taffy and changing them triggers a relayout; style properties are

package/src/view.tsx

@@ -1,7 +1,8 @@
 import type { LayoutProps, PointerProps } from "@solidrt/core"
-import type { StyleProps } from "./types"
+import type { StyleProps, TransitionProps } from "./types"
+import { splitTransition, transitionEndFor } from "./types"
 
-export interface ViewProps extends PointerProps {
+export interface ViewProps extends PointerProps, TransitionProps {
   children?: any
   ref?: (node: { id: number }) => void
   layout?: LayoutProps
@@ -13,8 +14,12 @@ export function View(props: ViewProps) {
     props.style?.backgroundColor != null || props.style?.borderRadius != null
   let hasBorder = () => (props.style?.borderWidth ?? 0) > 0
 
+  let split = () => splitTransition(props.transition)
+
   return (
     <view
+      transition={split().root}
+      onTransitionEnd={transitionEndFor("root", props.onTransitionEnd)}
       ref={props.ref}
       {...props.layout}
       x={props.style?.x}
@@ -45,6 +50,8 @@ export function View(props: ViewProps) {
     >
       {hasBackground() ? (
         <d-rect
+          transition={split().background}
+          onTransitionEnd={transitionEndFor("background", props.onTransitionEnd)}
           color={props.style?.backgroundColor ?? "transparent"}
           radius={props.style?.borderRadius}
         />
@@ -53,6 +60,8 @@ export function View(props: ViewProps) {
       {hasBorder() ? (
         <d-rect
           drawStyle="stroke"
+          transition={split().border}
+          onTransitionEnd={transitionEndFor("border", props.onTransitionEnd)}
           color={props.style?.borderColor ?? "transparent"}
           strokeWidth={props.style?.borderWidth}
           radius={props.style?.borderRadius}