KQ-1273 · PLACE/CARD

Place Card

A venue card with a small drawn map: hovering the card or moving keyboard focus into it zooms the map toward the pin on the glide spring, closing in about a point by the door so the pin holds still while streets thin and blocks grow, then draws the walk from you to the door and sets its dashes marching while the pin hops once on the recoil spring; markers and the walk keep their size on screen at any zoom, and the march runs only while the card is looked at, on screen and visible. Under the map a clock dial around the closing time shows the opening hours, a dot at now and an arc to closing whose sweep glides when now moves, read from a now prop in the venue's time zone. Directions opens numbered steps on a measured height that glides open, focus moves to the first step, Up and Down choose a step and light its stretch of the walk with a marker that glides to its start, and Escape closes the list and returns focus to the button.

KQ-1273 · PLACE/CARD

Coldbrook Roasters

Coffee and bakery · 14 Basin Street

Open

Closes in 2 h 14 min

5 min

walk · 400 m

open · closes in 2 h 14 min · 400 m walk

Open it on the Studio stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/place-card

Props

name: string; default "Coldbrook Roasters"; The venue: the card's heading and the map's accessible name.
kind: string; default "Coffee and bakery"; What kind of place it is, under the name.
address: string; default "14 Basin Street"; Under the name, after the kind.
now: Date | number; default —; The moment the hours are read at. Without it the card keeps its own clock, read from the first frame after mount and paused while the page is hidden.
timeZone: string; default "UTC"; The venue's IANA time zone, used to read now, so the server and the browser agree.
opensAt: string; default "07:30"; Today's opening time, 24-hour HH:MM.
closesAt: string; default "22:00"; Today's closing time, 24-hour HH:MM; earlier than opensAt means after midnight.
map: PlaceMap; default defaultPlaceMap; The neighbourhood: world size, streets, river, parks, blocks, the venue's building, and the walk's path from you (its first point) to the door (its last).
steps: PlaceStep[]; default defaultPlaceSteps; The walk as numbered steps ({ id, text, meters, at }), each starting at a point of map.path.
expanded / defaultExpanded: boolean; default false; Whether the directions are open, controlled or initial.
onExpandedChange: (expanded: boolean) => void; default —; Fires from the press or the Escape that opened or closed the directions.
onStepSelect: (index: number) => void; default —; A step was chosen from the list, by press or arrow key.
zoom: number; default 1.8; How far looking at the card zooms the map toward the pin, 1 to 3.
route: "dashes" | "dots" | "line"; default "dashes"; How the walk is drawn: dashes that march to the door, footstep dots that march, or a still line.
hours: "12h" | "24h"; default "24h"; The clock the hours are read on: the dial's 12 or 24 hours and every time on the card.
drawDuration: number; default 700; How long the walk takes to draw from you to the door, in ms.
walkSpeed: number; default 80; Walking pace that turns the steps' metres into minutes, in metres a minute.
directionsLabel: string; default "Directions"; The directions button's text while closed.
closeLabel: string; default "Hide directions"; The same button's text while the steps are open; the button is always as wide as the longer label.
size: "sm" | "md" | "lg"; default "md"; The map's height: 136, 168 or 200 px.
accent: string; default "var(--accent-bright)"; The walk, the you marker and the hours arc, any CSS colour.
pinColor: string; default "var(--danger)"; The pin's pigment, any CSS colour; drawn at a fixed lightness so it reads the same in both themes.
sound: boolean; default false; Play a swish as the visitor opens or closes the directions and a plip, rising with the step number, as they choose a step.
disabled: boolean; default false; Nothing zooms or opens, and the card is drawn at reduced strength.
className: string; default —; Classes for the card.

Prop	Type	Default	Description
name	string	"Coldbrook Roasters"	The venue: the card's heading and the map's accessible name.
kind	string	"Coffee and bakery"	What kind of place it is, under the name.
address	string	"14 Basin Street"	Under the name, after the kind.
now	Date \| number	—	The moment the hours are read at. Without it the card keeps its own clock, read from the first frame after mount and paused while the page is hidden.
timeZone	string	"UTC"	The venue's IANA time zone, used to read now, so the server and the browser agree.
opensAt	string	"07:30"	Today's opening time, 24-hour HH:MM.
closesAt	string	"22:00"	Today's closing time, 24-hour HH:MM; earlier than opensAt means after midnight.
map	PlaceMap	defaultPlaceMap	The neighbourhood: world size, streets, river, parks, blocks, the venue's building, and the walk's path from you (its first point) to the door (its last).
steps	PlaceStep[]	defaultPlaceSteps	The walk as numbered steps ({ id, text, meters, at }), each starting at a point of map.path.
expanded / defaultExpanded	boolean	false	Whether the directions are open, controlled or initial.
onExpandedChange	(expanded: boolean) => void	—	Fires from the press or the Escape that opened or closed the directions.
onStepSelect	(index: number) => void	—	A step was chosen from the list, by press or arrow key.
zoom	number	1.8	How far looking at the card zooms the map toward the pin, 1 to 3.
route	"dashes" \| "dots" \| "line"	"dashes"	How the walk is drawn: dashes that march to the door, footstep dots that march, or a still line.
hours	"12h" \| "24h"	"24h"	The clock the hours are read on: the dial's 12 or 24 hours and every time on the card.
drawDuration	number	700	How long the walk takes to draw from you to the door, in ms.
walkSpeed	number	80	Walking pace that turns the steps' metres into minutes, in metres a minute.
directionsLabel	string	"Directions"	The directions button's text while closed.
closeLabel	string	"Hide directions"	The same button's text while the steps are open; the button is always as wide as the longer label.
size	"sm" \| "md" \| "lg"	"md"	The map's height: 136, 168 or 200 px.
accent	string	"var(--accent-bright)"	The walk, the you marker and the hours arc, any CSS colour.
pinColor	string	"var(--danger)"	The pin's pigment, any CSS colour; drawn at a fixed lightness so it reads the same in both themes.
sound	boolean	false	Play a swish as the visitor opens or closes the directions and a plip, rising with the step number, as they choose a step.
disabled	boolean	false	Nothing zooms or opens, and the card is drawn at reduced strength.
className	string	—	Classes for the card.