@preset.nz/ux-kit 0.0.0-stage → 0.1.0

package/src/components/toolbar.tsx

@@ -0,0 +1,307 @@
+import * as React from "react"
+import { Toolbar as ToolbarPrimitive } from "@base-ui/react/toolbar"
+
+import { cn } from "../lib/utils"
+import { buttonVariants } from "./button"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger,
+} from "./dropdown-menu"
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip"
+
+// Toolbar: props and callbacks only, no app state. The rules (native-apps.md,
+// ux-patterns.md): icon only, tooltip with name and shortcut, groups split by
+// separators, toggles show a pressed state, and every item is a command that
+// also lives in the menu. The toolbar is a subset of the menu, not a second
+// home for commands.
+//
+// Two ways in. Data-driven: `<Toolbar groups={[[item, item], [item]]} onCommand={run} />`
+// where `id` is the menu's command id. Composed: `ToolbarGroup`, `ToolbarSeparator`,
+// `ToolbarSpacer` and `ToolbarButton` as children, for anything the table cannot say.
+//
+// Roving focus and arrow-key navigation come from Base UI's Toolbar. Disabled
+// buttons stay focusable and keep their tooltip, which is how a gated item
+// says why it is gated (Oblique's `disabledHint`, M&T's `disabledReason`).
+
+/** An entry in a dropdown item's menu. */
+interface ToolbarMenuEntry {
+  id: string
+  label: string
+  shortcut?: string
+  /** Default true. */
+  enabled?: boolean
+}
+
+/** One toolbar item. `id` is the command id shared with the menu. */
+interface ToolbarItemSpec {
+  id: string
+  label: string
+  icon: React.ReactNode
+  /** Shown in the tooltip, in the platform's own notation ("⌘S"). */
+  shortcut?: string
+  /** Default true. */
+  enabled?: boolean
+  /** Replaces the shortcut in the tooltip while the item is disabled. */
+  disabledReason?: string
+  /** Present (true or false) makes the item a toggle. Absent means a plain button. */
+  pressed?: boolean
+  /** Present makes the item a dropdown; picking an entry calls `onCommand(entry.id)`. */
+  menu?: ToolbarMenuEntry[]
+}
+
+function Toolbar({
+  className,
+  ...props
+}: React.ComponentProps<typeof ToolbarPrimitive.Root>) {
+  return (
+    <ToolbarPrimitive.Root
+      data-slot="toolbar"
+      className={cn(
+        "flex items-center gap-1 border-b border-border bg-background px-2 py-1 data-[orientation=vertical]:w-fit data-[orientation=vertical]:flex-col data-[orientation=vertical]:border-r data-[orientation=vertical]:border-b-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ToolbarGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof ToolbarPrimitive.Group>) {
+  return (
+    <ToolbarPrimitive.Group
+      data-slot="toolbar-group"
+      className={cn("flex items-center gap-0.5 data-[orientation=vertical]:flex-col", className)}
+      {...props}
+    />
+  )
+}
+
+function ToolbarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof ToolbarPrimitive.Separator>) {
+  return (
+    <ToolbarPrimitive.Separator
+      data-slot="toolbar-separator"
+      className={cn(
+        "mx-1 h-5 w-px shrink-0 bg-border data-[orientation=horizontal]:mx-0 data-[orientation=horizontal]:my-1 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/** Pushes what follows to the far end (the right-panel toggle sits there). */
+function ToolbarSpacer({ className, ...props }: React.ComponentProps<"div">) {
+  return <div data-slot="toolbar-spacer" className={cn("flex-1", className)} {...props} />
+}
+
+function TooltipBody({
+  label,
+  shortcut,
+  disabledReason,
+}: Pick<ToolbarItemSpec, "label" | "shortcut" | "disabledReason">) {
+  return (
+    <>
+      <span>{label}</span>
+      {disabledReason ? (
+        <span className="opacity-70">{disabledReason}</span>
+      ) : shortcut ? (
+        <kbd data-slot="kbd" className="rounded-sm bg-background/20 px-1 font-sans text-[11px]">
+          {shortcut}
+        </kbd>
+      ) : null}
+    </>
+  )
+}
+
+const buttonClass = (pressed?: boolean) =>
+  cn(
+    buttonVariants({ variant: "ghost", size: "icon" }),
+    "data-disabled:cursor-default data-disabled:opacity-40 data-disabled:hover:bg-transparent",
+    pressed && "bg-muted text-foreground"
+  )
+
+interface ToolbarButtonProps
+  extends Omit<ToolbarItemSpec, "id" | "menu">,
+    Omit<React.ComponentProps<typeof ToolbarPrimitive.Button>, "children" | "aria-label"> {}
+
+/** One icon button: plain, or a toggle when `pressed` is given. Tooltip shows label and shortcut. */
+function ToolbarButton({
+  label,
+  icon,
+  shortcut,
+  enabled = true,
+  disabledReason,
+  pressed,
+  className,
+  ...props
+}: ToolbarButtonProps) {
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <ToolbarPrimitive.Button
+            data-slot="toolbar-button"
+            aria-label={label}
+            aria-pressed={pressed}
+            disabled={!enabled}
+            className={cn(buttonClass(pressed), className)}
+            {...props}
+          />
+        }
+      >
+        {icon}
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        <TooltipBody
+          label={label}
+          shortcut={shortcut}
+          disabledReason={enabled ? undefined : disabledReason}
+        />
+      </TooltipContent>
+    </Tooltip>
+  )
+}
+
+interface ToolbarDropdownProps extends Omit<ToolbarItemSpec, "id" | "menu" | "pressed"> {
+  entries: ToolbarMenuEntry[]
+  onCommand?: (id: string) => void
+}
+
+/** An icon button that opens a menu of commands. Entries are menu items, so they show shortcuts too. */
+function ToolbarDropdown({
+  label,
+  icon,
+  shortcut,
+  enabled = true,
+  disabledReason,
+  entries,
+  onCommand,
+}: ToolbarDropdownProps) {
+  return (
+    <DropdownMenu>
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <DropdownMenuTrigger
+              render={
+                <ToolbarPrimitive.Button
+                  data-slot="toolbar-dropdown"
+                  aria-label={label}
+                  disabled={!enabled}
+                  className={buttonClass()}
+                />
+              }
+            />
+          }
+        >
+          {icon}
+        </TooltipTrigger>
+        <TooltipContent side="bottom">
+          <TooltipBody
+            label={label}
+            shortcut={shortcut}
+            disabledReason={enabled ? undefined : disabledReason}
+          />
+        </TooltipContent>
+      </Tooltip>
+      <DropdownMenuContent align="start">
+        {entries.map((e) => (
+          <DropdownMenuItem
+            key={e.id}
+            disabled={e.enabled === false}
+            onClick={() => onCommand?.(e.id)}
+          >
+            {e.label}
+            {e.shortcut ? <DropdownMenuShortcut>{e.shortcut}</DropdownMenuShortcut> : null}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+/** Renders one spec as a button, toggle or dropdown. */
+function ToolbarItem({
+  item,
+  onCommand,
+}: {
+  item: ToolbarItemSpec
+  onCommand?: (id: string) => void
+}) {
+  if (item.menu) {
+    return <ToolbarDropdown {...item} entries={item.menu} onCommand={onCommand} />
+  }
+  return <ToolbarButton {...item} onClick={() => onCommand?.(item.id)} />
+}
+
+interface ToolbarItemsProps
+  extends Omit<React.ComponentProps<typeof Toolbar>, "children"> {
+  /** Groups of items; a separator is drawn between groups. */
+  groups: ToolbarItemSpec[][]
+  /** Called with the item's (or menu entry's) id. The app runs the same command the menu does. */
+  onCommand?: (id: string) => void
+  /** Pinned to the far left, before the groups (the left-panel toggle). */
+  leading?: ToolbarItemSpec[]
+  /** Pinned to the far right (the right-panel toggle). */
+  trailing?: ToolbarItemSpec[]
+  /** Extra content between the groups and the trailing items: a slot for anything custom. */
+  children?: React.ReactNode
+}
+
+/** The data-driven form: a toolbar from an item table. */
+function ToolbarItems({
+  groups,
+  onCommand,
+  leading,
+  trailing,
+  children,
+  ...props
+}: ToolbarItemsProps) {
+  const lead = leading?.length ? [leading] : []
+  const all = [...lead, ...groups.filter((g) => g.length > 0)]
+  return (
+    <Toolbar {...props}>
+      {all.map((group, i) => (
+        <React.Fragment key={i}>
+          {i > 0 && <ToolbarSeparator />}
+          <ToolbarGroup>
+            {group.map((item) => (
+              <ToolbarItem key={item.id} item={item} onCommand={onCommand} />
+            ))}
+          </ToolbarGroup>
+        </React.Fragment>
+      ))}
+      {children}
+      {trailing?.length ? (
+        <>
+          <ToolbarSpacer />
+          <ToolbarGroup>
+            {trailing.map((item) => (
+              <ToolbarItem key={item.id} item={item} onCommand={onCommand} />
+            ))}
+          </ToolbarGroup>
+        </>
+      ) : null}
+    </Toolbar>
+  )
+}
+
+export {
+  Toolbar,
+  ToolbarButton,
+  ToolbarDropdown,
+  ToolbarGroup,
+  ToolbarItem,
+  ToolbarItems,
+  ToolbarSeparator,
+  ToolbarSpacer,
+}
+export type { ToolbarItemSpec, ToolbarMenuEntry }

package/src/components/tooltip.tsx

@@ -0,0 +1,54 @@
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
+
+import { cn } from "../lib/utils"
+
+// Base UI: `delay` (ms) replaces Radix's `delayDuration`. Triggers take
+// `render={<Button />}` where Radix used `asChild`.
+function TooltipProvider({ delay = 0, ...props }: TooltipPrimitive.Provider.Props) {
+  return <TooltipPrimitive.Provider data-slot="tooltip-provider" delay={delay} {...props} />
+}
+
+function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({ ...props }: TooltipPrimitive.Trigger.Props) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  side = "top",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  children,
+  ...props
+}: TooltipPrimitive.Popup.Props &
+  Pick<TooltipPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <TooltipPrimitive.Popup
+          data-slot="tooltip-content"
+          className={cn(
+            "z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        >
+          {children}
+          <TooltipPrimitive.Arrow className="z-50 size-2.5 rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
+        </TooltipPrimitive.Popup>
+      </TooltipPrimitive.Positioner>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }

package/src/graphics/adsr.ts

@@ -0,0 +1,70 @@
+import { clamp, type Curve } from "@preset.nz/math"
+
+import type { CurveConstraint } from "./curve-edits"
+
+/** An ADSR envelope's four controls. Times are in the curve's x units; sustain is a level, 0..1. */
+export interface Adsr {
+  attack: number
+  decay: number
+  sustain: number
+  release: number
+}
+
+/**
+ * The curve an ADSR draws: start at rest, peak, sustain level, end at rest, with the sustain
+ * mark on the third point. Shard's sliders and the editor both write these four points.
+ */
+export function adsrCurve({ attack, decay, sustain, release }: Adsr): Curve {
+  const a = Math.max(0, attack)
+  const d = Math.max(0, decay)
+  const r = Math.max(0, release)
+  const s = clamp(sustain, 0, 1)
+  return {
+    points: [
+      { x: 0, y: 0, basis: "linear" },
+      { x: a, y: 1, basis: "linear" },
+      { x: a + d, y: s, basis: "linear" },
+      { x: a + d + r, y: 0, basis: "linear" },
+    ],
+    sustain: 2,
+  }
+}
+
+/** The ADSR a curve draws, or `null` when it no longer has that shape. */
+export function adsrOf(curve: Curve): Adsr | null {
+  const [p0, p1, p2, p3] = curve.points
+  if (curve.points.length !== 4 || !p0 || !p1 || !p2 || !p3 || curve.sustain !== 2) return null
+  if (p0.x !== 0 || p0.y !== 0 || p1.y !== 1 || p3.y !== 0) return null
+  return { attack: p1.x - p0.x, decay: p2.x - p1.x, sustain: p2.y, release: p3.x - p2.x }
+}
+
+/**
+ * The limits that keep a curve an ADSR. No points are added or removed and sustain stays on the
+ * third point. The start is pinned at rest, the peak's level at 1 and the end's at rest. Moving
+ * a point changes only the stage that ends there, and the later points ride along, so a longer
+ * attack doesn't eat the decay. The whole shape stays within `maxX`.
+ */
+export function constrainAdsr(maxX = Infinity): CurveConstraint {
+  return (next, prev) => {
+    if (next.points.length !== 4 || prev.points.length !== 4 || next.sustain !== 2) return null
+    const was = durations(prev)
+    const now = durations(next)
+    // The stage whose end moved takes the new length; the others keep theirs.
+    const moved = [1, 2, 3].find((i) => next.points[i]!.x !== prev.points[i]!.x)
+    const len = was.map((d, k) => (moved === k + 1 ? Math.max(0, now[k]!) : d))
+    const over = len[0]! + len[1]! + len[2]! - maxX
+    if (over > 0 && moved !== undefined) len[moved - 1] = Math.max(0, len[moved - 1]! - over)
+    const ys = [0, 1, clamp(next.points[2]!.y, 0, 1), 0]
+    let x = 0
+    const points = next.points.map((p, i) => {
+      if (i > 0) x += len[i - 1]!
+      return { ...p, x, y: ys[i]! }
+    })
+    return { points, sustain: 2 }
+  }
+}
+
+function durations(curve: Curve): number[] {
+  const p = curve.points
+  return [p[1]!.x - p[0]!.x, p[2]!.x - p[1]!.x, p[3]!.x - p[2]!.x]
+}