#!/bin/bash
# tikzphysics-help — quick reference for the tikzphysics TikZ library
# Usage: tikzphysics-help [shape]
# Examples:
#   tikzphysics-help          — list everything
#   tikzphysics-help wedge    — show wedge details
#   tikzphysics-help platform — show platform details

BOLD="\033[1m"
DIM="\033[2m"
RESET="\033[0m"
CYAN="\033[36m"
GREEN="\033[32m"
YELLOW="\033[33m"

print_header() {
  echo -e "\n${BOLD}${CYAN}tikzphysics v1.1.0${RESET} — TikZ-native physics diagram library"
  echo -e "${DIM}Load: \\\\usepackage{tikzphysics}  or  \\\\usetikzlibrary{tikzphysics.ramps, tikzphysics.mechanics}${RESET}\n"
}

print_all() {
  print_header

  echo -e "${BOLD}SUBMODULES${RESET}"
  echo "  tikzphysics.surface     platforms, wedges, flat strips"
  echo "  tikzphysics.ramps       straight and circular continuous ramps"
  echo "  tikzphysics.mechanics   blocks, springs, pulleys, tangent strings"
  echo "  tikzphysics.optics      mirrors, lenses, slabs, prisms"
  echo "  tikzphysics.core        shared utilities (auto-loaded)"

  echo -e "\n${BOLD}STYLES (use as \\\\node[style, ...])${RESET}"
  echo -e "  ${GREEN}platform${RESET}         general two-wall platform"
  echo -e "  ${GREEN}platform-left${RESET}    L-shaped platform, wall on left"
  echo -e "  ${GREEN}platform-right${RESET}   L-shaped platform, wall on right"
  echo -e "  ${GREEN}platform-both${RESET}    U-shaped platform, walls on both sides"
  echo -e "  ${GREEN}wedge${RESET}            right triangle (inclined plane)"
  echo -e "  ${GREEN}ramp${RESET}             wall, floor, and linear incline in one body"
  echo -e "  ${GREEN}curved-ramp${RESET}      circular contact surface with filled body"
  echo -e "  ${GREEN}ground${RESET}           flat strip, surface on top"
  echo -e "  ${GREEN}ceiling${RESET}          flat strip, surface on bottom"
  echo -e "  ${GREEN}wall-left${RESET}        vertical strip, surface on right"
  echo -e "  ${GREEN}wall-right${RESET}       vertical strip, surface on left"
  echo -e "  ${GREEN}block${RESET}            rectangular block"
  echo -e "  ${GREEN}spring${RESET}           coil node with attachment anchors"
  echo -e "  ${GREEN}pulley${RESET}           circle with axle dot"
  echo -e "  ${GREEN}concave-mirror${RESET}   concave spherical mirror"
  echo -e "  ${GREEN}convex-mirror${RESET}    convex spherical mirror"
  echo -e "  ${GREEN}convex-lens${RESET}      symmetric biconvex lens"
  echo -e "  ${GREEN}concave-lens${RESET}     symmetric biconcave lens"
  echo -e "  ${GREEN}slab${RESET}             unfilled parallel-sided rectangular slab"
  echo -e "  ${GREEN}prism${RESET}            unfilled isosceles triangular prism"
  echo -e "  ${DIM}Collision-safe alternatives retain the physics... names.${RESET}"

  echo -e "\n${BOLD}KEYS${RESET}"
  echo -e "  ${YELLOW}Native size:${RESET} minimum width, minimum height, minimum size  ${DIM}(preferred)${RESET}"
  echo -e "  ${YELLOW}Platforms:${RESET}  physics platform width, physics platform depth, physics strip width,"
  echo "              physics wall angle, physics left wall angle, physics right wall angle"
  echo -e "  ${YELLOW}Wedge:${RESET}     wedge width, wedge height, wedge angle,"
  echo "              wedge right angle at (br|bl|top)"
  echo "              collision-safe aliases: physics wedge ..."
  echo -e "  ${YELLOW}Ramp:${RESET}      minimum width, ramp run/rise/angle, ramp depth,"
  echo "              ramp wall height/width, ramp direction, ramp guide length"
  echo -e "  ${YELLOW}Curved:${RESET}    curved ramp radius/angle/back extension"
  echo -e "  ${YELLOW}Flat:${RESET}      physics ground width/depth, physics ceiling width/depth,"
  echo "              physics wall thickness/height"
  echo -e "  ${YELLOW}Block:${RESET}     physics block width, physics block height"
  echo -e "  ${YELLOW}Spring:${RESET}    minimum width, pre/post length, amplitude,"
  echo "              segment length, aspect"
  echo -e "  ${YELLOW}Pulley:${RESET}    physics pulley diameter, physics pulley axle radius,"
  echo "              physics pulley axle color, physics string start/end solution, physics string wrap"
  echo -e "  ${YELLOW}Mirrors:${RESET}   mirror radius, mirror thickness, mirror aperture angle"
  echo -e "  ${YELLOW}Convex:${RESET}    convex lens radius/thickness/aperture angle"
  echo -e "  ${YELLOW}Concave:${RESET}   concave lens radius/thickness/aperture angle"
  echo -e "  ${YELLOW}Slab:${RESET}      minimum width/height, slab width/height"
  echo -e "  ${YELLOW}Prism:${RESET}     minimum width/height, prism width/height, prism apex angle"

  echo -e "\n${BOLD}DEBUG${RESET}"
  echo "  physics debug/anchors=true   numbered dots + legend"
  echo "  physics debug/keys=true      keys box; native names preferred for sizing"
  echo "  physics debug/all=true       both"

  echo -e "\n${BOLD}NUMERIC ANCHORS${RESET}"
  echo "  <edge>-0 through <edge>-100 on straight edges"
  echo "  front-T / back-T on lenses and slabs; base/left/right-T on prism"
  echo "  shorthand .T: mirror surface; lens/slab front; prism left face"
  echo "  ramp .T: primary contact surface; tangent-before/after-T and normal-T"

  echo -e "\n${DIM}Run: tikzphysics-help platform|wedge|ramp|block|spring|pulley|flat|optics for details${RESET}"
}

print_platform() {
  print_header
  echo -e "${BOLD}PLATFORMS${RESET}  platform (general) / platform-left / platform-right / platform-both"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  echo "  minimum width             = 5cm   (alias: physics platform width)"
  echo "  minimum height            = 2cm   (alias: physics platform depth)"
  echo "  physics strip width       = 0.3cm"
  echo "  physics wall angle        = -90°"
  echo "  physics left wall angle   = -90°   (both only)"
  echo "  physics right wall angle  = -90°   (both only)"
  echo -e "\n${YELLOW}Anchors:${RESET}"
  echo "  Floor:  floor-tl, floor-tr, floor-br, floor-bl"
  echo "          floor-top-mid, floor-bottom-mid, floor-left-mid,"
  echo "          floor-right-mid, floor-center"
  echo "  Wall:   wall-A (outer-near), wall-B (inner-miter),"
  echo "          wall-C (inner-far), wall-D (outer-far)"
  echo "          wall-outer-mid, wall-inner-mid, wall-near-mid,"
  echo "          wall-far-mid, wall-center"
  echo "  Corner: corner (fixed point on the continuous contact line)"
  echo "          left-corner, right-corner (both-wall platform)"
  echo "  Both:   prefix wall anchors with left- or right-"
  echo -e "\n${YELLOW}Numeric edges:${RESET}"
  echo "  floor-top-T, floor-bottom-T, floor-left-T, floor-right-T"
  echo "  wall-outer-T, wall-inner-T, wall-near-T, wall-far-T"
  echo "  (T = 0..100)"
  echo -e "\n${YELLOW}Complete example:${RESET} examples/short-names-platform-pulley.tex"
}

print_wedge() {
  print_header
  echo -e "${BOLD}WEDGE${RESET}  wedge"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  echo "  minimum width            = 4cm   (alias: wedge width)"
  echo "  wedge height             = (derived)"
  echo "  wedge angle              = (mode default: 30° or 45°)"
  echo "  wedge right angle at     = br  (br|bl|top)"
  echo "  collision-safe aliases: physics wedge width/height/angle/right angle at"
  echo -e "\n${YELLOW}Precedence:${RESET} wedge angle > wedge height > mode default"
  echo -e "\n${YELLOW}Anchors:${RESET}"
  echo "  bl, br, top, base-mid, right-mid, slope-mid,"
  echo "  slope-right-mid (top mode), centroid, mid"
  echo "  + compass: center, north, south, east, west, etc."
  echo -e "\n${YELLOW}Numeric edges:${RESET}  base-T, right-T, slope-T  (T = 0..100)"
  echo -e "\n${YELLOW}Complete example:${RESET} examples/short-names-wedge-variants.tex"
}

print_ramp() {
  print_header
  echo -e "${BOLD}RAMPS${RESET}  ramp / ramp-left / curved-ramp / curved-ramp-left"
  echo -e "\n${YELLOW}Straight keys (defaults):${RESET}"
  echo "  minimum width       = 8.6cm"
  echo "  ramp run            = 2.6cm"
  echo "  ramp angle          = 30°   (authoritative when explicit)"
  echo "  ramp rise           = derived"
  echo "  ramp wall height    = 1.5cm"
  echo "  ramp wall width     = 0.25cm"
  echo "  ramp depth          = 0.25cm"
  echo "  angle marker        = \\physicsrampangle{R}{\$30^\\circ\$}"
  echo -e "\n${YELLOW}Circular keys (defaults):${RESET}"
  echo "  curved ramp floor length    = 2cm"
  echo "  curved ramp radius          = 4cm"
  echo "  curved ramp angle           = 90°"
  echo "  curved ramp back extension  = 1cm"
  echo "  ramp direction              = right  (right|left)"
  echo "  ramp guide length           = 0.5cm"
  echo -e "\n${YELLOW}Primary anchors:${RESET} surface-start/mid/end, surface-T, .T (full surface)"
  echo "  tangent-before-T, tangent-after-T, normal-T"
  echo "  straight: floor-start/mid/end, ramp-foot/mid/top, wall-top/mid/bottom"
  echo "  curved: floor-start/mid/end, curve-T, curve-start/mid/end, curve-center"
  echo "          curve-tangent-before/after-T, curve-normal-T"
  echo -e "\n${YELLOW}Complete examples:${RESET}"
  echo "  ramp-straight-system.tex, ramp-curved-system.tex, ramps-gallery.tex"
}

print_block() {
  print_header
  echo -e "${BOLD}BLOCK${RESET}  block"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  echo "  minimum width   = 1cm   (alias: physics block width)"
  echo "  minimum height  = 1cm   (alias: physics block height)"
  echo -e "\n${YELLOW}Anchors:${RESET}  center, north, south, east, west, + corners"
}

print_spring() {
  print_header
  echo -e "${BOLD}SPRING${RESET}  spring"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  echo "  minimum width         = 3cm   (complete end-to-end length)"
  echo "  pre length            = 5pt"
  echo "  post length           = 5pt"
  echo "  amplitude             = 4.5pt"
  echo "  segment length        = 4.5pt"
  echo "  aspect                = 0.5"
  echo "  collision-safe aliases: physics spring ..."
  echo -e "\n${YELLOW}Native styling:${RESET} draw, line width, rotate, scale"
  echo -e "\n${YELLOW}Anchors:${RESET} start, end, coil-start, coil-mid, coil-end, + compass"
  echo -e "\n${YELLOW}Complete example:${RESET} examples/mechanics-spring-block.tex"
}

print_pulley() {
  print_header
  echo -e "${BOLD}PULLEY${RESET}  pulley"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  echo "  minimum size                   = 1cm   (alias: physics pulley diameter)"
  echo "  physics pulley axle radius  = 2pt  (set 'none' to hide)"
  echo "  physics pulley axle color   = black"
  echo -e "\n${YELLOW}Tangent string:${RESET}"
  echo "  \\physicsstringoverpulley{start}{pulley}{end}"
  echo "  physics string start solution = 2"
  echo "  physics string end solution   = 1"
  echo "  physics string route          = surface-right  (surface-right|over|under|shortest)"
  echo "  physics string wrap           = clockwise  (clockwise|counterclockwise|shortest)"
  echo -e "\n${YELLOW}Complete examples:${RESET}"
  echo "  mechanics-pulley-flat-plane.tex"
  echo "  mechanics-block-pulley.tex"
  echo "  mechanics-pulley-bent-platform.tex"
  echo "  mechanics-pulley-two-masses.tex"
  echo -e "\n${YELLOW}Anchors:${RESET}  center, north, south, east, west, + corners"
}

print_flat() {
  print_header
  echo -e "${BOLD}FLAT STRIPS${RESET}  ground / ceiling / wall-left / wall-right"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  echo "  ground:  minimum width/height = 6cm / 0.3cm"
  echo "  ceiling: minimum width/height = 2cm / 0.3cm"
  echo "  walls:   minimum width/height = 0.3cm / 3cm"
  echo "  Convenience aliases: physics ground ..., physics ceiling ..., physics wall ..."
  echo -e "\n${YELLOW}Anchors:${RESET}"
  echo "  top-left, top-right, top-mid, bottom-left, bottom-right,"
  echo "  bottom-mid, left-mid, right-mid, surface, center"
  echo -e "\n${YELLOW}Numeric edges:${RESET}  top-T, bottom-T, left-T, right-T  (T = 0..100)"
}

print_optics() {
  print_header
  echo -e "${BOLD}OPTICS${RESET}  concave-mirror / convex-mirror / convex-lens / concave-lens / slab / prism"
  echo -e "\n${YELLOW}Mirror keys:${RESET}"
  echo "  mirror radius          = 5cm"
  echo "  mirror thickness       = 0.25cm"
  echo "  mirror aperture angle = 30°"
  echo -e "\n${YELLOW}Convex lens keys:${RESET}"
  echo "  convex lens radius          = 5cm"
  echo "  convex lens thickness       = 0.2cm  (edge thickness)"
  echo "  convex lens aperture angle = 25°"
  echo -e "\n${YELLOW}Concave lens keys:${RESET}"
  echo "  concave lens radius          = 5cm"
  echo "  concave lens thickness       = 0.2cm  (on-axis thickness)"
  echo "  concave lens aperture angle = 25°"
  echo -e "\n${YELLOW}Slab keys:${RESET}"
  echo "  minimum width / height = 1.2cm / 3cm"
  echo "  aliases: slab width / slab height"
  echo -e "\n${YELLOW}Prism keys:${RESET}"
  echo "  minimum width / height = 3cm / 2.6cm"
  echo "  aliases: prism width / prism height"
  echo "  prism apex angle = derived  (explicit value overrides height)"
  echo -e "\n${YELLOW}Mirror anchors:${RESET}"
  echo "  center, vertex, surface-mid, back-mid,"
  echo "  surface-top, surface-bottom, back-top, back-bottom,"
  echo "  top, bottom, east, west"
  echo -e "${YELLOW}Lens anchors:${RESET} front/back-mid/top/bottom, top, bottom, east, west"
  echo -e "\n${YELLOW}Slab anchors:${RESET} front, back, front/back-top/bottom, top, bottom"
  echo -e "${YELLOW}Prism anchors:${RESET} apex, base-left/right/mid, left/right/entry/exit-mid"
  echo -e "\n${YELLOW}Numeric surfaces:${RESET}"
  echo "  mirror: surface-T, back-T; lens: front-T, back-T"
  echo "  slab: front-T, back-T, top-T, bottom-T"
  echo "  prism: base-T, left-T, right-T  (T = 0..100)"
  echo "  shorthand name.T uses mirror surface, lens/slab front, or prism left"
  echo -e "\n${YELLOW}Complete examples:${RESET} optics-components.tex, optics-ray-composition.tex"
  echo "  optics-complete-ray-diagrams.tex"
}

case "${1:-all}" in
  all|-h|--help) print_all ;;
  platform*) print_platform ;;
  wedge)     print_wedge ;;
  ramp|ramps|curved-ramp) print_ramp ;;
  block)     print_block ;;
  spring)    print_spring ;;
  pulley)    print_pulley ;;
  flat|ground|ceiling|wall) print_flat ;;
  mirror|concave-mirror|convex-mirror|convex-lens|concave-lens|slab|prism|optics) print_optics ;;
  *)
    echo "Unknown: $1. Try: platform, wedge, ramp, block, spring, pulley, flat, optics" >&2
    exit 2
    ;;
esac