#!/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.2.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${RESET}  node styles unless marked as a path style"
  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-left-up${RESET} left-wall preset pointing upward"
  echo -e "  ${GREEN}platform-right-up${RESET} right-wall preset pointing upward"
  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 path style: \\draw[spring] (A)--(B)"
  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}  platform width/depth, strip width, wall angle,"
  echo "              left wall angle, 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}      ground width/depth, ceiling width/depth, wall thickness/height"
  echo -e "  ${YELLOW}Block:${RESET}     minimum width/height or block width/height"
  echo -e "  ${YELLOW}Spring:${RESET}    pre/post length, amplitude,"
  echo "              segment length, aspect"
  echo -e "  ${YELLOW}Pulley:${RESET}    pulley diameter, pulley axle radius/color,"
  echo "              string start/end solution, string route, 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 '  show anchors / show keys: add to any named physics node'
  echo '  \physicshelp{index} or \physicshelp{spring}: reference inside tikzpicture'
  echo '  every block/.style={...}, every spring/.style={...}: reusable defaults'
  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 "  Syntax: (node.family-T), with integer T=0..100 and no % sign"
  echo "  0=start, 50=midpoint, 100=end; direction is family-specific"
  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 anchors for a beginner percentage-anchor guide${RESET}"
  echo -e "${DIM}Run: tikzphysics-help geometry for named geometry values${RESET}"
  echo -e "${DIM}Other topics: platform|wedge|ramp|block|spring|pulley|flat|optics${RESET}"
}

print_anchors() {
  print_header
  echo -e "${BOLD}PERCENTAGE ANCHORS${RESET}  (node.family-T)"
  echo -e "\n${YELLOW}Mental model:${RESET}"
  echo "  node    = the name given after a node, for example W"
  echo "  family  = the selected edge or surface, for example slope"
  echo "  T       = integer 0..100; write 25, not 25%"
  echo "  0=start, 50=halfway, 100=end"
  echo -e "\n${YELLOW}Example:${RESET}"
  echo "  \\node[wedge] (W) at (0,0) {};"
  echo "  \\node[block,anchor=south] at (W.slope-50) {\$m\$};"
  echo "  \\fill[red] (W.slope-25) circle (1.5pt);"
  echo -e "\n${YELLOW}Important directions:${RESET}"
  echo "  platform floor-top-T: right corner -> left corner"
  echo "  platform wall-outer-T: platform corner -> far wall end"
  echo "  wedge base-T: bl -> br; right-T: br -> top; slope-T: top -> bl"
  echo "  ramp surface-T: surface-start -> surface-end along the whole path"
  echo "  curved ramp curve-T: circular portion only"
  echo "  optics surface/front/back-T: bottom -> top"
  echo "  prism base-T: left -> right; left-T: apex -> base-left"
  echo -e "\n${YELLOW}Short form:${RESET}"
  echo "  (R.T) = ramp surface-T"
  echo "  (L.T) = mirror surface-T, lens/slab front-T, or prism left-T"
  echo "  platforms and wedges require the explicit family name"
  echo "  explicit family names are recommended while learning"
  echo -e "\n${YELLOW}Coordinate projection:${RESET}"
  echo "  (A |- B) takes x from A and y from B"
  echo "  (A -| B) takes x from B and y from A"
  echo "  horizontal wall-to-block: (R.wall-mid |- B.west)"
  echo -e "\n${YELLOW}Complete example:${RESET} examples/percentage-anchors-beginner.tex"
  echo "  projection example: examples/coordinate-projection.tex"
}

print_platform() {
  print_header
  echo -e "${BOLD}PLATFORMS${RESET}  platform / platform-left / platform-right / platform-both"
  echo "           presets: platform-left-up / platform-right-up"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  echo "  minimum width             = 5cm   (alias: physics platform width)"
  echo "  minimum height            = 2cm   (alias: physics platform depth)"
  echo "  strip width               = 0.25cm (alias: physics strip width)"
  echo "  wall angle                = -90°   (alias: physics wall angle)"
  echo "  left wall angle           = -90°   (both only)"
  echo "  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 "  default material pattern = dots"
  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}Geometry values:${RESET}  \\geometryvalue{W}{left angle},"
  echo "  right angle, top angle, slope angle, edge directions, width, height"
  echo -e "\n${YELLOW}Complete examples:${RESET} examples/short-names-wedge-variants.tex"
  echo "  examples/wedge-geometry-values.tex"
}

print_geometry() {
  print_header
  echo -e "${BOLD}NAMED WEDGE GEOMETRY${RESET}  \\geometryvalue{node}{property}"
  echo "  collision-safe accessor: \\tikzphysicsgeometryvalue{node}{property}"
  echo -e "\n${YELLOW}Interior angles:${RESET}"
  echo "  left angle   at bl"
  echo "  right angle  at br"
  echo "  top angle    at top"
  echo -e "\n${YELLOW}Local directions:${RESET}  degrees CCW from local +x"
  echo "  base direction, left edge direction, right edge direction"
  echo "  slope angle = surface rotation at slope-mid"
  echo "  aliases: slope direction, surface angle; right slope angle uses slope-right-mid"
  echo -e "\n${YELLOW}Other values:${RESET} width, height, right angle at"
  echo -e "\n${YELLOW}Example:${RESET}"
  echo "  \\node[wedge,wedge angle=30] (W) at (0,0) {};"
  echo "  \\node[block,rotate=\\geometryvalue{W}{slope angle},anchor=south]"
  echo "    at (W.slope-mid) {\$m\$};"
  echo "  angle label: \\geometryvalue{W}{left angle}"
  echo -e "\n${YELLOW}Rule:${RESET} name and finish the wedge before querying it."
  echo "  Values are local; use anchor-based sloped placement after independent"
  echo "  node rotation or non-uniform scaling."
  echo -e "\n${YELLOW}Complete source:${RESET} examples/wedge-geometry-values.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    = 2.5cm"
  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 "  collision-safe aliases add the physics prefix"
  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   (aliases: block width, physics block width)"
  echo "  minimum height  = 1cm   (aliases: block height, physics block height)"
  echo -e "\n${YELLOW}Anchors:${RESET}  center, north, south, east, west, + corners"
}

print_spring() {
  print_header
  echo -e "${BOLD}SPRING PATH${RESET}  \\draw[spring] (A) -- (B);"
  echo -e "\n${YELLOW}Keys (defaults):${RESET}"
  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}Geometry:${RESET} the path endpoints set total length and direction"
  echo -e "\n${YELLOW}Native styling:${RESET} draw, line width, color, scale"
  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   (aliases: pulley diameter, physics pulley diameter)"
  echo "  pulley axle radius    = 2pt  (set 'none' to hide)"
  echo "  pulley axle color     = black"
  echo -e "\n${YELLOW}Tangent string:${RESET}"
  echo "  \\physicsstringoverpulley{start}{pulley}{end}"
  echo "  string start solution = 2"
  echo "  string end solution   = 1"
  echo "  string route          = surface-right  (surface-right|over|under|shortest)"
  echo "  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: ground ..., ceiling ..., wall ..."
  echo "  Collision-safe aliases add the physics prefix."
  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 "  collision-safe aliases add the physics prefix"
  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"
}

print_explore() {
  cat <<'HELP'
Inside a tikzpicture:
  \node[wedge,show anchors,show keys] (W) {};
  \physicshelp{index}
  \physicshelp{spring}

Select anchors:
  physics debug/anchor list={bl,br,top}
  physics debug/anchor families={surface}
  physics debug/anchor samples={0,25,50,75,100}

show anchors=false and show keys=false override inherited settings.
Keys cards list defaults, not live node values.
See docs/reference.md and examples/debug-explorer.tex.

New mechanics:
  \draw[rope] (A) to[over pulley=P] (B);
  \pic (A) {pin-support};
  \pic (B) at (4,0) {roller-support};
  \draw[rod] (A-pivot) -- (B-pivot);
  \pic (P) {pendulum};
  particle, disk, ring: node styles
  force, velocity, acceleration, torque, rod: path styles
HELP
}

case "${1:-all}" in
  all|-h|--help) print_all ;;
  debug|explore|defaults|mechanics|rope|particle|disk|ring|force|velocity|acceleration|torque|rod|pin-support|roller-support|pendulum) print_explore ;;
  platform*) print_platform ;;
  wedge)     print_wedge ;;
  ramp|ramps|curved-ramp) print_ramp ;;
  block)     print_block ;;
  spring)    print_spring ;;
  pulley)    print_pulley ;;
  geometry|geometry-value|geometry-values|value|values) print_geometry ;;
  anchor|anchors|percentage|percent) print_anchors ;;
  flat|ground|ceiling|wall) print_flat ;;
  mirror|concave-mirror|convex-mirror|convex-lens|concave-lens|slab|prism|optics) print_optics ;;
  *)
    echo "Unknown: $1. Try: anchors, geometry, platform, wedge, ramp, block, spring, pulley, flat, optics" >&2
    exit 2
    ;;
esac