@pathmx/player 0.5.0

package/controls.tsx

@@ -0,0 +1,716 @@
+import { createRoot, type Root } from "react-dom/client"
+import {
+  useEffect,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactNode,
+} from "react"
+import { PathMXProvider } from "@pathmx/react"
+import {
+  ActionButton,
+  Button,
+  Drawer,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerTrigger,
+  Label,
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Separator,
+  Switch,
+  ToggleGroup,
+  ToggleGroupItem,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@pathmx/react/ui"
+import {
+  ChevronDown,
+  ChevronUp,
+  ExternalLink,
+  LayoutGrid,
+  MessageSquareQuote,
+  Play,
+  SlidersHorizontal,
+  Square,
+  X,
+} from "lucide-react"
+import type { SourceDescription } from "@pathmx/core"
+import type { PlayAction } from "./actions.ts"
+import type { PlayGuideFrame } from "./guide.ts"
+import { PlayProgress, type PlayProgressBlock } from "./progress.tsx"
+import { PLAY_THEMES, sourcePlayTheme, type PlayThemeId } from "./themes.ts"
+
+export type PlayMode = "focus" | "presentation"
+export type PlayIntensity = "low" | "medium" | "high"
+export type PlayThemeChoice = "source" | PlayThemeId
+
+type PlayCommands = {
+  start(): void
+  previous(): void
+  next(): void
+  setMode(mode: PlayMode): void
+  setIntensity(intensity: PlayIntensity): void
+  setTheme(theme: PlayThemeChoice): void
+  setGuide(enabled: boolean): void
+  setNotes(enabled: boolean): void
+  setGrid(open: boolean): void
+  setAutoHide(enabled: boolean): void
+  setExpanded(expanded: boolean): void
+  exit(): void
+  activateAction(index: number): void
+}
+
+type ControlsState = {
+  description: SourceDescription
+  actions: readonly PlayAction[]
+  intensity: PlayIntensity
+  mode: PlayMode
+  playing: boolean
+  index: number
+  total: number
+  label: string
+  blocks: readonly PlayProgressBlock[]
+  theme: PlayThemeChoice
+  guide: boolean
+  notes: boolean
+  grid: boolean
+  autoHide: boolean
+  visible: boolean
+  guideFrame?: PlayGuideFrame
+  note?: string
+}
+
+type ControlsStore = Readonly<{
+  subscribe(listener: () => void): () => void
+  snapshot(): ControlsState
+}>
+
+export const MOBILE_CONTROLS_QUERY = "(max-width: 42rem), (pointer: coarse)"
+
+function subscribeMobile(listener: () => void) {
+  const media = matchMedia(MOBILE_CONTROLS_QUERY)
+  media.addEventListener("change", listener)
+  return () => media.removeEventListener("change", listener)
+}
+
+function mobileSnapshot() {
+  return matchMedia(MOBILE_CONTROLS_QUERY).matches
+}
+
+function useMobileControls() {
+  return useSyncExternalStore(subscribeMobile, mobileSnapshot, () => false)
+}
+
+function TooltippedAction(
+  props: Readonly<{
+    label: string
+    tooltip?: string
+    keyShortcuts?: string
+    icon: ReactNode
+    onClick(): void
+    disabled?: boolean
+    pressed?: boolean
+    appearance?: "plain" | "floating"
+    className?: string
+  }>,
+) {
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <ActionButton
+            label={props.label}
+            icon={props.icon}
+            appearance={props.appearance}
+            disabled={props.disabled}
+            pressed={props.pressed}
+            className={props.className}
+            aria-keyshortcuts={props.keyShortcuts}
+            onClick={props.onClick}
+          />
+        }
+      />
+      <TooltipContent>{props.tooltip ?? props.label}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+function NavigationActions({
+  state,
+  commands,
+  close,
+  mobile,
+}: Readonly<{
+  state: ControlsState
+  commands: PlayCommands
+  close(): void
+  mobile: boolean
+}>) {
+  const actions = [
+    {
+      label: "Previous Beat",
+      tooltip: "Previous Beat (↑)",
+      keyShortcuts: "ArrowUp",
+      icon: <ChevronUp aria-hidden="true" />,
+      disabled: state.index <= 0,
+      run: commands.previous,
+    },
+    {
+      label: "Next Beat",
+      tooltip: "Next Beat (↓)",
+      keyShortcuts: "ArrowDown",
+      icon: <ChevronDown aria-hidden="true" />,
+      disabled: state.index >= state.total - 1,
+      run: commands.next,
+    },
+    {
+      label: state.grid ? "Close Block Grid" : "Block Grid",
+      tooltip: state.grid ? "Close Block Grid (G)" : "Block Grid (G)",
+      keyShortcuts: "G",
+      icon: <LayoutGrid aria-hidden="true" />,
+      pressed: state.grid,
+      run: () => {
+        commands.setGrid(!state.grid)
+        close()
+      },
+    },
+    {
+      label: "Stop Play",
+      tooltip: "Stop Play (Esc)",
+      keyShortcuts: "Escape",
+      icon: <Square aria-hidden="true" fill="currentColor" stroke="none" />,
+      appearance: "floating" as const,
+      run: commands.exit,
+    },
+  ]
+  return (
+    <div className="pmx-play-panel-actions" role="group" aria-label="Playback">
+      {actions.map((action) => (
+        <div className="pmx-play-panel-action" key={action.label}>
+          <TooltippedAction
+            label={action.label}
+            tooltip={action.tooltip}
+            keyShortcuts={action.keyShortcuts}
+            icon={action.icon}
+            onClick={action.run}
+            disabled={action.disabled}
+            pressed={action.pressed}
+            appearance={action.appearance}
+          />
+          {mobile && <span>{action.label}</span>}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function SettingRow({
+  label,
+  children,
+  stacked = false,
+}: Readonly<{ label: string; children: ReactNode; stacked?: boolean }>) {
+  return (
+    <div className="pmx-play-setting" data-stacked={stacked ? "" : undefined}>
+      <span>{label}</span>
+      <div>{children}</div>
+    </div>
+  )
+}
+
+function SettingsModel({
+  state,
+  commands,
+  close,
+  mobile,
+}: Readonly<{
+  state: ControlsState
+  commands: PlayCommands
+  close(): void
+  mobile: boolean
+}>) {
+  const defaultTheme = sourcePlayTheme(state.description)
+  const defaultThemeLabel =
+    PLAY_THEMES.find((theme) => theme.id === defaultTheme)?.label ?? "Native"
+  const themeItems = {
+    source: `Source default · ${defaultThemeLabel}`,
+    ...Object.fromEntries(PLAY_THEMES.map((theme) => [theme.id, theme.label])),
+  }
+  return (
+    <>
+      <NavigationActions
+        state={state}
+        commands={commands}
+        close={close}
+        mobile={mobile}
+      />
+      <Separator />
+      <div className="pmx-play-settings-scroll">
+        <SettingRow label="Mode">
+          <ToggleGroup
+            value={[state.mode]}
+            onValueChange={(value) => {
+              const mode = value[0]
+              if (mode === "focus" || mode === "presentation") {
+                commands.setMode(mode)
+              }
+            }}
+            spacing={0}
+          >
+            <ToggleGroupItem value="focus">Focus</ToggleGroupItem>
+            <ToggleGroupItem value="presentation">Slides</ToggleGroupItem>
+          </ToggleGroup>
+        </SettingRow>
+        <Separator />
+        <SettingRow label="Theme" stacked={mobile}>
+          <Select
+            items={themeItems}
+            value={state.theme}
+            onValueChange={(value) => {
+              if (
+                value === "source" ||
+                PLAY_THEMES.some((theme) => theme.id === value)
+              ) {
+                commands.setTheme(value as PlayThemeChoice)
+              }
+            }}
+          >
+            <SelectTrigger aria-label="Presentation theme">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent data-pmx-player-control="">
+              <SelectItem value="source">
+                Source default · {defaultThemeLabel}
+              </SelectItem>
+              {PLAY_THEMES.map((theme) => (
+                <SelectItem key={theme.id} value={theme.id}>
+                  {theme.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </SettingRow>
+        <Separator />
+        <SettingRow label="Intensity">
+          <ToggleGroup
+            value={[state.intensity]}
+            onValueChange={(value) => {
+              const intensity = value[0]
+              if (
+                intensity === "low" ||
+                intensity === "medium" ||
+                intensity === "high"
+              ) {
+                commands.setIntensity(intensity)
+              }
+            }}
+            spacing={0}
+          >
+            <ToggleGroupItem value="low">Low</ToggleGroupItem>
+            <ToggleGroupItem value="medium">Medium</ToggleGroupItem>
+            <ToggleGroupItem value="high">High</ToggleGroupItem>
+          </ToggleGroup>
+        </SettingRow>
+        <Separator />
+        <Label className="pmx-play-switch-row">
+          <span>Beat Guide</span>
+          <Switch
+            checked={state.guide}
+            onCheckedChange={commands.setGuide}
+            aria-label="Show Beat Guide"
+          />
+        </Label>
+        <Separator />
+        <Label className="pmx-play-switch-row">
+          <span>Notes</span>
+          <Switch
+            checked={state.notes}
+            onCheckedChange={commands.setNotes}
+            aria-label="Show presenter notes"
+          />
+        </Label>
+        <Separator />
+        <Label className="pmx-play-switch-row">
+          <span>Controls</span>
+          <span className="pmx-play-switch-value">Auto-hide</span>
+          <Switch
+            checked={state.autoHide}
+            onCheckedChange={commands.setAutoHide}
+            aria-label="Auto-hide controls"
+          />
+        </Label>
+      </div>
+    </>
+  )
+}
+
+function SettingsSurface({
+  state,
+  commands,
+}: Readonly<{ state: ControlsState; commands: PlayCommands }>) {
+  const mobile = useMobileControls()
+  const [open, setOpen] = useState(false)
+  useEffect(() => {
+    if (state.playing) return
+    setOpen(false)
+  }, [state.playing])
+  useEffect(() => commands.setExpanded(open), [commands, open])
+  const changeOpen = (next: boolean) => setOpen(next)
+  const trigger = (
+    <ActionButton
+      label="Player controls"
+      icon={<SlidersHorizontal aria-hidden="true" />}
+      appearance="floating"
+      size="sm"
+      pressed={open}
+      className="pmx-play-controls-trigger"
+    />
+  )
+
+  if (mobile) {
+    return (
+      <Drawer
+        open={open}
+        onOpenChange={changeOpen}
+        showSwipeHandle
+        swipeDirection="down"
+      >
+        <DrawerTrigger render={trigger} />
+        <DrawerContent data-pmx-player-control="">
+          <DrawerHeader>
+            <DrawerTitle>Player controls</DrawerTitle>
+            <DrawerDescription>
+              Navigation, focus, presentation, and visibility settings.
+            </DrawerDescription>
+          </DrawerHeader>
+          <SettingsModel
+            state={state}
+            commands={commands}
+            close={() => changeOpen(false)}
+            mobile
+          />
+        </DrawerContent>
+      </Drawer>
+    )
+  }
+
+  return (
+    <Popover open={open} onOpenChange={changeOpen}>
+      <PopoverTrigger render={trigger} />
+      <PopoverContent data-pmx-player-control="">
+        <PopoverHeader>
+          <PopoverTitle>Player controls</PopoverTitle>
+          <PopoverDescription>
+            Navigation, focus, presentation, and visibility settings.
+          </PopoverDescription>
+        </PopoverHeader>
+        <SettingsModel
+          state={state}
+          commands={commands}
+          close={() => changeOpen(false)}
+          mobile={false}
+        />
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+function ActiveActions({
+  actions,
+  activate,
+}: Readonly<{
+  actions: readonly PlayAction[]
+  activate(index: number): void
+}>) {
+  if (!actions.length) return null
+  return (
+    <div className="pmx-play-actions" aria-label="Actions for this Beat">
+      {actions.map((action, index) => (
+        <Button
+          key={`${action.label}:${index}`}
+          variant="outline"
+          size="sm"
+          data-pmx-play-action=""
+          onPointerDown={(event) => {
+            if (event.pointerType === "mouse") event.preventDefault()
+          }}
+          onClick={() => activate(index)}
+        >
+          <kbd>{index + 1}</kbd>
+          <span>{action.label}</span>
+          {action.external && <ExternalLink aria-hidden="true" size={15} />}
+        </Button>
+      ))}
+    </div>
+  )
+}
+
+function BeatGuide({ state }: Readonly<{ state: ControlsState }>) {
+  const frame = state.guideFrame
+  return (
+    <div
+      className="pmx-play-guide"
+      data-highlight={frame?.highlight ?? "none"}
+      data-visible={state.playing && state.guide && frame ? "true" : "false"}
+      aria-hidden="true"
+      style={
+        frame
+          ? ({
+              "--pmx-guide-left": `${frame.guideLeft}px`,
+              "--pmx-guide-top": `${frame.top}px`,
+              "--pmx-guide-height": `${frame.height}px`,
+              "--pmx-guide-target-left": `${frame.targetLeft}px`,
+              "--pmx-guide-target-width": `${frame.targetWidth}px`,
+            } as CSSProperties)
+          : undefined
+      }
+    >
+      <span data-pmx-play-guide-bar="" />
+      <span data-pmx-play-guide-highlight="" />
+    </div>
+  )
+}
+
+function PresenterNote({ state }: Readonly<{ state: ControlsState }>) {
+  if (
+    !state.playing ||
+    state.mode !== "presentation" ||
+    state.grid ||
+    !state.notes ||
+    !state.note
+  ) {
+    return null
+  }
+  return (
+    <aside
+      className="pmx-play-note"
+      role="note"
+      aria-label="Presenter note"
+      aria-live="polite"
+    >
+      <MessageSquareQuote aria-hidden="true" />
+      <div dangerouslySetInnerHTML={{ __html: state.note }} />
+    </aside>
+  )
+}
+
+function PlayerChrome({
+  state,
+  commands,
+}: Readonly<{ state: ControlsState; commands: PlayCommands }>) {
+  return (
+    <TooltipProvider>
+      <PlayProgress
+        playing={state.playing}
+        mode={state.mode}
+        index={state.index}
+        total={state.total}
+        blocks={state.blocks}
+      />
+      <BeatGuide state={state} />
+      <PresenterNote state={state} />
+      {state.playing && state.mode === "presentation" && (
+        <ActionButton
+          label="Exit Play"
+          icon={<X aria-hidden="true" />}
+          appearance="floating"
+          className="pmx-play-exit"
+          data-pmx-player-control=""
+          onClick={commands.exit}
+        />
+      )}
+      <div
+        className="pmx-play-chrome"
+        data-pmx-player-control=""
+        data-pmx-play-state={state.playing ? "playing" : "idle"}
+        data-pmx-play-visible={
+          state.visible || !state.autoHide ? "" : undefined
+        }
+      >
+        {!state.playing ? (
+          <TooltippedAction
+            label="Play document"
+            tooltip="Play document (Command/Control + Enter)"
+            keyShortcuts="Meta+Enter Control+Enter"
+            icon={<Play aria-hidden="true" fill="currentColor" stroke="none" />}
+            appearance="floating"
+            className="pmx-play-launcher"
+            onClick={commands.start}
+          />
+        ) : (
+          <>
+            <ActiveActions
+              actions={state.actions}
+              activate={commands.activateAction}
+            />
+            <SettingsSurface state={state} commands={commands} />
+          </>
+        )}
+        <output
+          className="pmx-ui-visually-hidden"
+          data-pmx-play-progress=""
+          aria-live="polite"
+        >
+          {state.total
+            ? `${state.index + 1} of ${state.total}: ${state.label}`
+            : ""}
+        </output>
+      </div>
+    </TooltipProvider>
+  )
+}
+
+function PlayerControlsApp({
+  store,
+  commands,
+}: Readonly<{ store: ControlsStore; commands: PlayCommands }>) {
+  const state = useSyncExternalStore(
+    store.subscribe,
+    store.snapshot,
+    store.snapshot,
+  )
+  return (
+    <PathMXProvider description={state.description}>
+      <PlayerChrome state={state} commands={commands} />
+    </PathMXProvider>
+  )
+}
+
+function playerViewportLayer(host: HTMLElement) {
+  const document = host.ownerDocument
+  const augmentations = document.querySelector<HTMLElement>(
+    "body > [data-pmx-augmentations]",
+  )
+  if (!augmentations) {
+    throw new Error("Missing PathMX augmentation layer.")
+  }
+  const existing = augmentations.querySelector<HTMLElement>(
+    ':scope > [data-pmx-augmentation="player"]',
+  )
+  if (existing) return existing
+  const layer = document.createElement("div")
+  layer.setAttribute("data-pmx-augmentation", "player")
+  augmentations.append(layer)
+  return layer
+}
+
+/** Mount Player chrome above authored layout and containing-block effects. */
+export function createPlayControls(
+  host: HTMLElement,
+  description: SourceDescription,
+  commands: PlayCommands,
+) {
+  const layer = playerViewportLayer(host)
+  let root: Root | undefined
+  let state: ControlsState = {
+    description,
+    actions: [],
+    intensity: "medium",
+    mode: "focus",
+    playing: false,
+    index: 0,
+    total: 0,
+    label: "",
+    blocks: [],
+    theme: "source",
+    guide: true,
+    notes: true,
+    grid: false,
+    autoHide: true,
+    visible: true,
+  }
+  const listeners = new Set<() => void>()
+  const store: ControlsStore = {
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    snapshot: () => state,
+  }
+  const update = (next: Partial<ControlsState>) => {
+    state = { ...state, ...next }
+    for (const listener of listeners) listener()
+  }
+  const mount = () => {
+    if (root) return
+    if (!layer.isConnected) {
+      const augmentations = host.ownerDocument.querySelector(
+        "body > [data-pmx-augmentations]",
+      )
+      if (!augmentations) throw new Error("Missing PathMX augmentation layer.")
+      augmentations.append(layer)
+    }
+    root = createRoot(layer)
+    root.render(<PlayerControlsApp store={store} commands={commands} />)
+  }
+  const unmount = () => {
+    root?.unmount()
+    root = undefined
+    layer.remove()
+  }
+  mount()
+  return {
+    mount,
+    unmount,
+    setDescription(description: SourceDescription) {
+      update({ description })
+    },
+    setActions(actions: readonly PlayAction[]) {
+      update({ actions })
+    },
+    setIntensity(intensity: PlayIntensity) {
+      update({ intensity })
+    },
+    setMode(mode: PlayMode) {
+      update({ mode })
+    },
+    setPlaying(playing: boolean) {
+      update({ playing })
+    },
+    setProgress(
+      index: number,
+      total: number,
+      label: string,
+      blocks: readonly PlayProgressBlock[],
+    ) {
+      update({ index, total, label, blocks })
+    },
+    setTheme(theme: PlayThemeChoice) {
+      update({ theme })
+    },
+    setGuide(guide: boolean) {
+      update({ guide })
+    },
+    setNotes(notes: boolean) {
+      update({ notes })
+    },
+    setGrid(grid: boolean) {
+      update({ grid })
+    },
+    setAutoHide(autoHide: boolean) {
+      update({ autoHide })
+    },
+    setVisible(visible: boolean) {
+      update({ visible })
+    },
+    setGuideFrame(guideFrame?: PlayGuideFrame) {
+      update({ guideFrame })
+    },
+    setNote(note?: string) {
+      update({ note })
+    },
+  }
+}

package/fragments.ts

@@ -0,0 +1,6 @@
+/** Return an authored Beat value that is safe to expose as a URL fragment. */
+export function explicitBeatFragment(value: string | null | undefined) {
+  const fragment = value?.trim()
+  if (!fragment || /[\s#]/u.test(fragment)) return
+  return fragment
+}