# Old builds of an app draw what they can of newer views
HUDKit, hudkit and the web shell say their version as they call HUD (the `place.hud/kit` client capability, and `callTool`'s `kit`), and HUD fits each tree to the kit drawing it: a client that says none is drawn for the oldest kit, 0.2.0. A view may gate a Stack, Pane or Bar on it, `"when": {"$kit": ">=0.3.0"}` or `"unless"`, and give any node a `fallback`: a component newer than the kit is sent as its children, else its fallback, else nothing. A release build of HUDKit, hudkit or the web renderer draws a component it doesn't know the same way, where a debug build still shows it isn't drawn yet. An app file's `"kits": {"oldest": "0.2.0"}` makes `hud check` warn where a view uses a component or prop newer than that with nothing around it for older kits.
notes: "Its children, one above another, gap apart (md where none is given; gap none sets them against one another, as a place's map over its grid). when (a path in its scope) draws it only where that holds something, and unless only where it holds nothing: neither null, false, 0, \"\" nor empty (a chat's unread messages, { \"when\": \"unreadCount\" }; a chat with someone's names, where a group's has its own, { \"unless\": \"kind.name\" }). mine (a path to a DID) draws it only where that is the signed-in person's, and others only where it is not (a chat's last message as \"You: …\" or as it is, { \"mine\": \"lastMessage.sender.did\" }); signed out, mine draws nothing and others draws. where, as List's, draws it only where its scope holds at each path what the path paired with it holds, or the literal of an {\"$is\": …} (a Germ button only for everyone, { \"where\": { \"joins.profile.messageMe.showButtonTo\": { \"$is\": \"everyone\" } } }). Among a List's children, a Stack with at (1 to 100) is not part of each item: it is drawn once, with the List's own scope, after that many items, on its first page alone (suggested follows after a feed's fifth gallery). measure content holds it to the host's reading width, centred, in a view drawn wider (a wide profile's header over its grid, { \"measure\": \"content\" }); in a box no wider, it changes nothing.",
notes: "Its children, one above another, gap apart (md where none is given; gap none sets them against one another, as a place's map over its grid). when (a path in its scope) draws it only where that holds something, and unless only where it holds nothing: neither null, false, 0, \"\" nor empty (a chat's unread messages, { \"when\": \"unreadCount\" }; a chat with someone's names, where a group's has its own, { \"unless\": \"kind.name\" }). when or unless may instead be { \"$kit\": a semver requirement }: drawn only for a kit (the renderer drawing it: the web's is the server's version, an app's its build's, one that says none the oldest) whose version it takes, or for unless does not, as a part using what newer kits draw ({ \"when\": { \"$kit\": \">=0.3.0\" } }) beside what older ones draw instead ({ \"unless\": { \"$kit\": \">=0.3.0\" } }). mine (a path to a DID) draws it only where that is the signed-in person's, and others only where it is not (a chat's last message as \"You: …\" or as it is, { \"mine\": \"lastMessage.sender.did\" }); signed out, mine draws nothing and others draws. where, as List's, draws it only where its scope holds at each path what the path paired with it holds, or the literal of an {\"$is\": …} (a Germ button only for everyone, { \"where\": { \"joins.profile.messageMe.showButtonTo\": { \"$is\": \"everyone\" } } }). Among a List's children, a Stack with at (1 to 100) is not part of each item: it is drawn once, with the List's own scope, after that many items, on its first page alone (suggested follows after a feed's fifth gallery). measure content holds it to the host's reading width, centred, in a view drawn wider (a wide profile's header over its grid, { \"measure\": \"content\" }); in a box no wider, it changes nothing.",
notes: "Its children side by side, wrapping; xs is the gap between things that belong together, as a check's mark and its name. A Stack in it takes the room the rest leave, so a mark stays beside the text it marks. wrap cut keeps them on one line, cutting short what does not fit: the first first, to a few characters, then those between it and the last, never the last (a post's author: its name, then its handle, never its time). wrap inline runs its Texts and Times on as words of one paragraph, a space between each, wrapping between words, as a notification's \"Alice and 3 others favorited your gallery 2h\" (a strong Text, two Texts and a Time).",
notes: "Two children side by side where its box holds both, else one under the other in their order: never hidden, never reordered. One is the main, taking the room left; the other the aside, at its narrowest: the second where side is end (the default), the first where side is start (a profile's picture beside its name and counts, { \"side\": \"start\", \"aside\": \"sm\" }). main and aside are the narrowest each goes side by side (sm, md or lg; md and sm by default). A child drawing nothing leaves the other alone, as it is.",
notes: "Plain text; clamp is about the most lines shown before \"more\": a longer value is cut at a word, an ellipsis after it, at about 44 characters a line, a line break ending one; prefix is written before the value (\"Reposted by \"), and nothing is drawn when the value does not resolve. strong is body text in a heavier weight, as a row's title; quote smaller and quieter, on one line, behind a rule at its left, as what a reply replies to. words gives one's own words for values ({ \"review-requested\": \"asked you to review\" }), a value it does not name drawn as it is; chars cuts the value to that many characters, as a commit's hash to 7. countNoun ([singular, plural]) follows a number with its noun, the singular after 1 (\"and \" before { \"$\": \"group.others\" }: and 1 other, and 3 others). A whole number of 10,000 or more with no prefix reads as a count, its thousands grouped (67,519).",
notes: "Markdown drawn safely (no HTML but <details> and its <summary>, drawn as a disclosure): markdown is CommonMark, gfm GitHub's (tables, task lists, strikethrough, bare links), as a pull's or a README's; or text with Bluesky richtext facets (links, mentions, tags); or detect, text written with none (a profile's description), its links, @mentions and #tags found as Bluesky's app finds them. Markdown's pictures show their alt text, but those pictures names: an array of { cid, url, width?, height? } (width and height in CSS pixels), each an https URL of the view's origins, drawn in place of an image whose URL is that url or a com.atproto.sync.getBlob URL with that cid, as a pull's attachments. clamp is about the most lines shown before \"Show more\", as a README's first 20: a longer text is cut at a word, an ellipsis after it, at about 44 characters a line, a line break ending one; markdown's blocks whole while they fit, then the next cut. style muted draws its runs smaller and quieter, as Text's muted: a feed's description under its name.",
since: FIRST,
},
Component {
name: "Time",
props: &[req!("value", Ty::Time)],
children: false,
notes: "A date and time, in the reader's own zone, in short: how long ago within a week (now, 5m, 3h, 2d), else the day (Nov 15, with the year when it is not this one); the whole date and time where a pointer hovers and as it is read aloud.",
notes: "One image: src is a blob ref (or an https URL of the view's origins); size avatar draws it small and round, as beside an author's name; face larger and round, as a post's author in a column beside the post (a Row of it and a Stack); large largest and round, as a profile's own at its head; icon small as an avatar, a rounded square holding the picture whole, as an app's icon; thumb a little larger, a rounded square the picture fills, cropped, as a notification's gallery at the end of its row. One with a size but thumb draws a placeholder where src resolves to nothing (an account with no avatar); one without, or a thumb, is left out. bleed true draws it to the edges of what holds it, square-cornered, as a photo app's feed draws a photo; showAlt true marks it ALT where it has alt text, which a tap shows over it. ring (a path, as Stack's when) rings a round one in the accent where the scope holds something there, as a photo app marks stories not yet seen ({ \"ring\": \"unviewedCount\" }); plus (a path too) marks a round one with a small + in the accent at its corner, as a photo app marks one's own face first in its stories (Your story, its literal first item { \"add\": true } with { \"plus\": \"add\" }). href, as Link's, makes a tap open that rather than what holds it, its alt read aloud: an author's picture opens their profile ({ \"href\": { \"$\": \"creator.did\" } }); where it resolves to nothing it is a picture alone.",
notes: "A small icon and a number, written short (1.2k), with label read aloud: as likes, from a counts join (joins.counts.likes). value binding an array counts its elements, as a query join's open pulls (joins.open.pulls); more binds what says there are more than that (the join's cursor), and when it holds anything the count is drawn N+. A value that is neither a number nor an array draws nothing.",
notes: "Exactly one of href or open. href: an at-uri opens the record in place; a DID or handle its repository; an https URL the host's browser. open takes List's forms, as a query to call ({ \"query\": \"com.example.getRepo\", \"params\": { \"repo\": { \"$\": \"uri\" } } }), and a link with open draws only when its label resolves, as its words alone where a param resolves to nothing; with sheet: true its screen opens over what is open (a story's comments over the story). A link whose open is the host's ({ \"host\": \"signOut\" }) draws nothing where its host does not do it. style button draws it as a button (a profile's Message), name as an account's name beside its picture (in the text's own colour, bold), muted in the muted text's colour and size, on one line cut with an ellipsis (a gallery's location under its author), link (the default) as words. icon is drawn before its words, and alone in a Bar or over a Slides' picture, its label then read aloud. share, an https address that href's value ends, makes it a way to share that address (the host's share sheet, else copied) rather than to open it: a profile's Share ({ \"label\": \"Share profile\", \"href\": { \"$\": \"actor.handle\" }, \"share\": \"https://grain.social/profile/\" }). copy, text put before href's value, makes it a way to copy that text rather than to open it: a profile's Copy handle ({ \"label\": \"Copy handle\", \"href\": { \"$\": \"actor.handle\" }, \"copy\": \"@\" }). fragment, a path to a DID, opens href's https address (with no fragment of its own) with that DID as its fragment, then + and the signed-in person's DID where one is signed in, as Germ asks of its messageMeUrl; where the path holds no DID, nothing is drawn ({ \"label\": \"Message on Germ\", \"href\": { \"$\": \"joins.profile.messageMe.messageMeUrl\" }, \"fragment\": \"actor.did\" }).",
notes: "A row of 2 to 6 tabs over what is drawn, as Open, Closed and Assigned over a repository's issues: items [{ \"label\": \"Closed\", \"open\": { \"query\": \"com.example.listIssues\", \"params\": { \"repo\": { \"$root\": \"params.repo\" }, \"state\": \"closed\" } } }, …], label short text, open as List's (params read from the scope, {\"$root\": path} too). Or a tab for each element of an array in the data, from (a binding, as the feeds a person pinned), each labelled by the path label within it and opening open (its params read from the element), those where keeps (as List's, {\"$is\": literal} too), up to 20; items are then the tabs where from holds no array (a person who pinned none). In place of open, opens: 1 to 4 { where?, open }, each element opening the first whose where it matches (one with no where, any), as a pinned camera opens its camera's feed and a pinned feed its own: [{ \"where\": { \"type\": { \"$is\": \"camera\" } }, \"open\": { \"query\": \"com.example.getFeed\", \"params\": { \"camera\": { \"$after\": [{ \"$\": \"id\" }, \"camera:\"] } } } }, …]; a param {\"$after\": [value, prefix]} is what the value holds after the prefix, and the tab is not drawn where it does not start so. The tab whose query is the one drawn now (its method, and each param it names as asked; of several, the one naming most) is marked, and with none marked, or fewer than two tabs, none are drawn; choosing another replaces what is drawn with its call, in place: the same tile or screen, never a new one. style strip draws them as a feed app's feeds: a line of words that scrolls sideways, the one drawn now underlined. Put it at the top of a query view, each tab one of the queries the view draws.",
notes: "A search field: the words a person types fill param of the query open names (as List's open, { \"query\": \"com.example.searchPosts\", \"params\": { … } }), and searching opens it. value binds the words searched already (a results view's { \"$\": \"params.q\" }), shown in the field. Where open is the query drawn now (its method, and each param it names as asked), searching again draws the answer in place, as a tab does; elsewhere it opens it. Put it at the top of a search's results view, and where a search starts (an app's explore page).",
notes: "A settings switch: label, about under it, on whether it is on now (a binding to a boolean; default where it holds none), and call, in a bundled view alone, the procedure a flip sends as the signed-in person, its input a template as an Action's call's is, with {\"$on\": true} wherever the new state goes, as { \"method\": \"com.example.setPreference\", \"service\": …, \"input\": { \"preference\": { \"$type\": \"com.example.defs#photoPref\", \"includeExif\": { \"$on\": true }, \"includeLocation\": { \"$first\": [{ \"$\": \"…includeLocation\" }, true] } } } }.",
notes: "A setting of one of a few values, the sibling of Toggle: label, about under it, options, 2 to 6 { label, value } (each value a string, as [{ \"label\": \"System\", \"value\": \"system\" }, { \"label\": \"Dark\", \"value\": \"dark\" }]), on the value chosen now (a binding; default, one of the values, where it holds none of them), and call, in a bundled view alone, the procedure a choice sends as the signed-in person, its input a template as a Toggle's, with {\"$on\": true} wherever the value chosen goes, as { \"method\": \"com.example.setPreference\", \"service\": …, \"input\": { \"preference\": { \"$type\": \"com.example.defs#themePref\", \"theme\": { \"$on\": true } } } }. Drawn as the platform draws a choice of so many: a segmented control of 2 or 3, rows to pick from of more.",
notes: "A small rounded square of a tint with a white glyph, as a settings row's: name is one of issue, pull, review, notification, repo, star, check, release, activity, search, people, feed, heart, follow, comment, reply, mention; tint one of green, blue, purple, gray, yellow, red, orange; either may bind a menu row's word ({ \"$\": \"icon\" }), and one that resolves to no such word draws nothing. names and tints give the glyph and tint for each value name and tint bind, a value they do not name taken as it is (a notification's reason: { \"name\": { \"$\": \"reason\" }, \"names\": { \"gallery-favorite\": \"heart\", \"follow\": \"follow\" }, \"tint\": { \"$\": \"reason\" }, \"tints\": { \"gallery-favorite\": \"red\", \"follow\": \"blue\" } }). style glyph draws the glyph alone in its tint's colour (red the heart's, blue the accent), level with an avatar beside it, as a notification's reason in a column before who did it. First in a Row of a menu's List (a Row of the Icon, a Text, and a Stat).",
notes: "What something is in, by role: roles names the role of each value (\"of/value\" first, where of binds what it is a state of, as an item's kind, then \"value\"), each role its own colour and icon: open-pull, draft-pull, merged, closed-pull, open-issue, closed-issue, success, failure, running, queued, skipped, neutral (any value not named). style mark draws the icon alone (its word read aloud, as a row's state or a check's), text the icon and word (the default), pill both on the role's colour, as a page's header. words as Text's; by default the value, capitalised. As { \"value\": { \"$\": \"state\" }, \"of\": { \"$\": \"kind\" }, \"roles\": { \"pull/open\": \"open-pull\", \"pull/closed\": \"closed-pull\", \"merged\": \"merged\", \"issue/open\": \"open-issue\", \"issue/closed\": \"closed-issue\" } }.",
notes: "A label on a pull or an issue: its name, tinted with its color (a hex #rrggbb; any other is none), its description as its title. Inline in a List of labels.",
notes: "One file's unified diff: a header (path, from where it was renamed from, status, lines added and removed) and, with rows, its rows in monospace with their old and new line numbers, unwrapped, scrolling sideways. Each row is { kind, old?, new?, text }: kinds names the kind of a line added, removed, a hunk's header and a note ({ \"added\": \"a\", \"removed\": \"d\", \"hunk\": \"h\", \"note\": \"x\" }), any other a line of context. note says why rows are not shown. Without rows, the header alone: a list of files changed.",
notes: "Its children are drawn once per item, with the item as their scope, in a style: rows, cards, grid, inline (side by side and wrapping, with no frame of their own: tags), chips (side by side and wrapping, each item a filled pill that opens it, its words small and strong: a photo app's cameras and places, its title a small capital label), strip (one row that scrolls sideways, its items one width: a photo app's stories over its feed), shelf (one row of cards that scrolls sideways: suggested accounts), or spread (one row its items share evenly, each centred: a profile's counts); a grid's min (sm, md or lg: a size its host sets) is the narrowest its tiles go, as many across as fit, and columns (1 to 6) the most across however wide its box is (a photo app's profile, three across: { \"style\": \"grid\", \"min\": \"sm\", \"columns\": 3 }). chevrons true ends each of its rows that opens something with a chevron, as a settings page's rows that open pages of their own (rows alone). more, chips' alone, is one chip more after the items, { \"label\": \"See all\", \"open\": { \"query\": … } }, drawn in the accent colour where limit left items out. title is a heading over it, drawn only when it has items, and empty what it says where its items would be when it has none (\"No open pulls\"). Clicking one opens open (by default the item's uri), and open false opens nothing, its children's own links and buttons still theirs (a gallery's comments): a binding to an at-uri opens that record, { query, params, service? } calls that query with params read from the item (as { \"query\": \"app.bsky.feed.getPostThread\", \"params\": { \"uri\": { \"$\": \"post.uri\" } } }). { \"url\": \"https://…\" } opens that page in the host's browser (a site's own page the app has no view of), and, in a bundled view alone, { \"host\": \"signOut\" } asks the host app to sign the account out, as an app's own Settings' Sign out: an item whose open its host does not do is left out. A param is literal JSON, a binding into the item, {\"$root\": path} into the view's own scope (a query view's params.repo, from inside a list), {\"$atUri\": [authority, collection, rkey]}, an at-uri built of three of those, or an array of those. items may be {\"$root\": path}, an array of the view's own scope, and where keeps only the elements matching the scope ({ \"commit\": \"sha\" }: those whose commit is the item's sha), as a commit's checks from an answer's array of every commit's; a value in {\"$not\": …} keeps those not matching it ({ \"uri\": { \"$not\": \"response.gallery.uri\" } }: an account's galleries but the one drawn). needs (a path) keeps only the items holding something there; mine (a path to a DID) keeps only the items whose DID there is the signed-in person's, and others leaves those out (a chat's members but oneself, { \"others\": \"did\" }; signed out, mine keeps none and others all); distinct (a path) keeps each value there once, its first item, and leaves out items with nothing there; limit (1 to 100) draws at most that many, after where, needs, mine, others and distinct: as a feed's events cut to the threads they touch ({ \"needs\": \"action.title\", \"distinct\": \"action.subject\", \"limit\": 8 }). items may also be a literal array of at most 20 objects, a menu's fixed rows, each the scope of its row: a value in one may be {\"$root\": path}, read from the view's own scope before the row is drawn (null where it holds nothing), and nothing else in it is read; an element's own open, written as List's, opens its row in place of the List's. As [{ \"label\": \"Issues\", \"icon\": \"issue\", \"tint\": \"green\", \"count\": { \"$root\": \"joins.issues.items\" }, \"more\": { \"$root\": \"joins.issues.cursor\" }, \"open\": { \"query\": \"com.example.listIssues\", \"params\": { \"actor\": { \"$root\": \"me.did\" } } } }, …], each row a Row of an Icon ({ \"$\": \"icon\" }, { \"$\": \"tint\" }), a Text and a Stat ({ \"$\": \"count\" }, more { \"$\": \"more\" }). first is one row written as such a literal item, drawn before the items where needs keeps it: oneself before who has stories ({ \"profile\": { \"$root\": \"joins.me\" }, \"label\": \"Your story\", \"open\": … }). pages true opens an item as one page of a pager of them all, full screen, a swipe going to the one beside it and an item's Slides running off its end going on, as a photo app goes through who has stories. An item whose open opens at a form (its compose) is a page only of the pager it opens itself, never of another's, and an open's unless (a path in the item) drops its compose where it holds something: Your story's { \"compose\": true, \"unless\": \"stories\" }, its stories { \"$root\": \"joins.mine.stories\" }, opens at the new story's form alone with none, and with some is a page among the others, the first, as a swipe back from the next reaches. shown, in a bundled view alone, is a procedure called as the signed-in person once the list is first shown, its input read from the view's scope (notifications marked seen: { \"method\": \"com.example.updateSeen\", \"service\": …, \"input\": { \"seenAt\": { \"$now\": true } } }). group draws items as one, as a photo app groups the favorites of one gallery: an item joins the first group whose first item holds the same at each of by's paths and whose time (an RFC 3339 path) is less than hours from its own, as { \"as\": \"group\", \"by\": [\"reason\", \"galleryUri\"], \"time\": \"createdAt\", \"hours\": 48, \"only\": { \"reason\": [\"gallery-favorite\", \"follow\"] }, \"distinct\": \"author.did\" }; only, where given, groups only items holding one of its values at its path, and distinct leaves out an item whose value there its group holds already. Grouping comes after the other filters; each group draws as its first item, as holding { items (the group's, in order), count, others (count less one, where there are more) }, every item a group of itself at least, each page grouped on its own.",
notes: "A tree, as a thread's replies: its children are the template drawn for each item, then the item's own children (the array at the path children names within it, as \"replies\") nested below, indented with a thread line, down to depth levels (1 to 8, by default 6). An item the template draws nothing of is left out. open takes List's forms but has no default: an item opens only when open is given. line \"face\" runs the line down the face column, for a template that starts with a Row whose first part is an Image of size face (a post's author, as the Bluesky app draws them); \"side\", the default, beside the items.",
notes: "A chain, as a thread's parents: walks from the object from binds, then its next (the path next names within it, as \"parent\"), and so on, up to depth (1 to 20, by default 10), and draws them oldest first, the last one walked at the top, each with its children as the template, joined by a thread line. open as Tree's: none unless given. line as Tree's: with \"face\", the line runs from under each item's face to the next's, the last's on into the face of what follows the chain (the post they lead to, starting with a face too), as FeedContext's.",
notes: "Photos in justified rows; with style stack each the full width at its own shape, one under another (a gallery that is the tile's subject, where src may be each photo's full size); with style carousel one at a time, the full width, swiped, dots saying which, as a photo app's feed shows a gallery, all in one frame (the narrowest photo's shape, no narrower than 9:16), a tap going to what holds it unless zoom, where it opens the photo full screen, to be pinched and zoomed (a gallery's own screen). src, alt and aspectRatio are read from each item. bleed and showAlt as Image's, for each photo. info, lines of words read from each photo's item (its camera), each { parts, join? } (join \" \" by default), each part { value: binding, prefix?, suffix?, omitRepeated? }, a part reading nothing left out and a line of none dropped; one with omitRepeated is left out too where the next part read starts with its first word, case aside (a camera's make, NIKON CORPORATION, before a model that names it, NIKON D750). As [{ \"parts\": [{ \"value\": { \"$\": \"exif.make\" }, \"omitRepeated\": true }, { \"value\": { \"$\": \"exif.model\" } }] }, { \"parts\": [{ \"value\": { \"$\": \"exif.fNumber\" } }, { \"value\": { \"$\": \"exif.iSO\" }, \"prefix\": \"ISO \" }], \"join\": \" · \" }]: a photo with any is drawn with an ⓘ in its bottom-left corner, mirroring ALT, that shows them over it, one of the two open at a time. srcset, in a stack or a carousel (each photo the full width), the sizes each photo comes in, each { src: binding, width: the pixels wide that URL is }, as [{ \"src\": { \"$\": \"thumb\" }, \"width\": 1000 }, { \"src\": { \"$\": \"fullsize\" }, \"width\": 2000 }]: a web page loads the smallest that fills the photo's width at the screen's density. like, the label of an Action in the same list item as the gallery (or, in none, the view's own), as \"Favorite\": a double-tap on a photo runs it where it is not done yet, never undoing it, a heart bursting where it was, as a photo app favorites a gallery; a tap then waits a moment to be sure it is not one.",
notes: "Pictures shown one at a time, as a photo app shows an account's stories: on black, the height of the screen, bars over them, one a picture, the one shown filling over seconds (2 to 15, by default 5) before the next; a tap on its right half goes on, on its left goes back, and a button beside its ⋯ pauses it. src, alt, aspectRatio, time (when it was posted) and place are read from each item; face and name, whose they are, from the scope, drawn over their top with the bars. href, read from each item as an Image's (a story's at-uri), is the screen each picture is: a tap never opens it, but an app's address follows it as it shows, so a link copied there opens that picture. Its children are drawn over each picture with its item as their scope: a Menu at the end of its top row, the rest (a comments Link, a Favorite Action) at its bottom-right, icons alone; like is the label of one of those Actions that a double-tap on the picture runs. reverse draws its items last first (an archive answered newest first, played oldest first). call, in a bundled view alone, is a procedure called as the signed-in person once each picture is first shown, its input read from the item (as { \"method\": \"com.example.markViewed\", \"service\": …, \"input\": { \"stories\": [{ \"$\": \"uri\" }] } }). start, a path in each item, begins at the item holding there what the query was asked to show first (the query tool's at, which an open's at gives: a story picked from an account's archive, { \"start\": \"uri\" }). With no pictures it draws its screen still, empty's words in the middle of it and its children under them, drawn with the view's scope: a way to add one (a Compose that posts a story, in a Stack whose mine is the account asked about).",
notes: "A few faces of some accounts, overlapping, and their names, as a profile's \"Followed by alice, bob and 3 others you follow\": the first three items' src, small and round, the first two's name, and lead before them; past those two, how many more, in countNoun's words ([\"other you follow\", \"others you follow\"]). open, read from the view's scope, is what a click opens (the whole list). No items, nothing. style pile draws the faces alone, an avatar's size, the first max (1 to 8, by default 5) and past them +N, each opening its href (read from its item: an account's DID), as a photo app's notification shows who favorited a gallery; with expand true, a way to list them all, each its face, name and handle (read from its item), opening its href.",
notes: "A grid of cover cards, one per item (each prop read from the item); clicking one opens it. count is a number, or an array whose elements it counts (a gallery's photos). stat is a number shown on the card beside its count, with statIcon. style tiles draws them as a profile's grid of square pictures, edge to edge, without words (an item counting more than one picture marked so), as a photo app's profile shows its galleries; cards (the default) with their words. min and columns as a List grid's: the narrowest a cover goes (sm, md or lg), and the most across (1 to 6), as { \"style\": \"tiles\", \"min\": \"sm\", \"columns\": 3 }, three across however wide. where and limit as List's: the items where keeps, at most limit of them, as a gallery's \"More from\" leaves out the gallery drawn ({ \"where\": { \"uri\": { \"$not\": \"response.gallery.uri\" } }, \"limit\": 6 }). select, in a bundled view alone, lets a person pick some and act on them at once, as a photo app deletes several of one's galleries: { label? (its button, Select), mine? (a path in the scope: offered only where it holds the signed-in person's DID, as a profile's own), action (Delete), noun ([gallery, galleries]), confirm? (said after \"Delete 3 galleries?\"), tone? (danger), and call ({ method, service, input }, as an Action's, its input read from each item picked, as { \"rkey\": { \"$rkey\": \"uri\" } }) or deletes ({ method, service, params }, as an Action's, its params read from each item picked, as { \"gallery\": { \"$\": \"uri\" } }) }: once asked, each is done in turn, one after another, and the view drawn again.",
notes: "An audio player: a track list, one per item (each prop read from the item), and a bar that plays them in turn; duration is in seconds. subtitleHref makes the subtitle a link, as Link's href: a DID opens that account (a track's artist, as its Rec's did).",
notes: "A map with a pin per item (each prop read from the item), in the accent, as a photo app maps its places. A pin's place is cell, an H3 cell index (as \"8a1969c9b397fff\"), at its centre, else lat and lng in degrees: give cell, or lat and lng; an item with neither has no pin. label names a pin, count is a whole number it stands for (a place's galleries), and clicking one opens it, as a List's items open (a literal item's own open in place of the Map's). height short (the default) is a page's header, still; tall can be moved and zoomed. zoom (1, the world, to 18, a street) centres it on its pins at that zoom; without, it fits them, no closer than a city (11). bleed as Image's. pins false draws no pins: the map still centres on its items' places as it would on their pins, a plain map of where they are. One place's header is one literal item, unpinned: { \"items\": [{ \"cell\": { \"$root\": \"params.location\" } }], \"cell\": { \"$\": \"cell\" }, \"pins\": false }. No places, nothing.",
notes: "A long-form post's body: value binds a content union object, as a site.standard.document's value.content. Draws pub.leaflet.content (every page's blocks: text with its facets, headers, images, code, lists, quotes, rules, Bluesky posts, website cards, galleries, buttons) and at.markpub.markdown (GitHub-flavoured markdown, drawn safely); any other content draws fallback (plain text, as value.textContent) as paragraphs, else a JSON tree.",
notes: "A Bluesky post's embed, drawn as Bluesky draws it: value binds the embed, in an AppView's view form (post.embed) or a record's (value.embed), or a strongRef to a post alone (a repost's value.subject), drawn as a quoted post. Images, or a gallery's, in justified rows; a link card (thumbnail, title, description, host); a video (played from the server's url, else its poster and a link to the post); a quoted post as a card, with its own embed one level down (depth 1, the default; 0 draws no quote's embed), or a feed, list, starter pack or labeler card; a quote in a record's form (a strongRef) is fetched from the AppView and drawn as the AppView's are; media with a quote, the media then the quote. did binds the post's author (for a record's blobs), uri the post's at-uri (for the link to it). An embed of another kind draws nothing.",
notes: "What a Bluesky feed item's post comes with, as the Bluesky app draws it: item binds the feed item (app.bsky.feed.defs#feedViewPost, as \".\" in a List of a feed's items). part above (the default), over the post: why it is in the feed (\"Reposted by\" its reposter, \"Pinned\"), then, for a reply that is not reposted, what it replies to: its thread's root where that is not its parent, \"View full thread\" where posts between them are left out, then its parent, each drawn with the children as the template and { post } as its scope (as a thread's items, so post.author.avatar, post.record.text, post.embed), joined by a thread line down to the post. part replyTo, under the post's author: \"Replied to\" its parent's author, a blocked post or a post, where that context is not drawn (reposted, parent deleted or blocked, or not sent). open is what a context post or that line opens, read from { post } (as { \"query\": \"app.bsky.feed.getPostThread\", \"params\": { \"uri\": { \"$\": \"post.uri\" } } }): none unless given.",
notes: "A button that writes as the signed-in account: create makes a record ({ collection, record }; the record's values may be bindings, {\"$now\": true} for the current time, {\"$strongRef\": path} for { uri, cid } of the record or view at path, {\"$rkey\": path} for the record key of the at-uri at path, {\"$root\": path} read from the view's own scope, or {\"$first\": [values]}, the first of 2 to 4 that resolves), delete deletes the record whose uri it binds ({ uri: binding }); exactly one of them, or, in a bundled view alone, interaction ({ event: app.bsky.feed.defs#requestMore or #requestLess }), which tells a feed more or less like the item, or call ({ method, service, input? }), which calls a procedure of the service through the account's PDS, its input a template as create's record is, as { \"method\": \"chat.bsky.convo.updateRead\", \"service\": \"did:web:api.bsky.chat#bsky_chat\", \"input\": { \"convoId\": { \"$\": \"id\" } } }, or deletes ({ method, service, params?, repeat?, collections?, then? }), which asks a query of the service, as the account, for a deletion plan, its params a template as call's input, and deletes what it answers, { writes: [{ collection, rkey }] }, the deletes of one com.atproto.repo.applyWrites, in the account's own repository at once, all or none (a gallery with its photos, as { \"method\": \"social.grain.gallery.getDeletionPlan\", \"service\": \"did:web:grain.social#grain_appview\", \"params\": { \"gallery\": { \"$\": \"response.gallery.uri\" } } }); with repeat true it asks again until a plan comes back empty, deleting an account's data a part at a time as the button counts the records gone, from the operator's own pages and apps alone; then ({ method, service, input? }, its input literal but {\"$did\": true}, the account's DID) is called once nothing is left, as the app's server forgetting the account; collections names the collections its deletes may reach beyond those the views write, which HUD asks at sign-in to delete. done is the label after it succeeds; a created record's button then deletes it again. existing (with create) binds the at-uri of the record the account already made, as an AppView's post.viewer.like: the button then starts done, and a click deletes that record. count binds how many there are, as post.likeCount: the button is then drawn as its icon and that number, counting it up or down as it is done or undone, its label read aloud, and where nothing can write it is drawn as a Stat of that number; no Stat of the same number goes beside it. closed binds whether it is closed (true): then it is drawn as a Stat of its count, or nothing. style button draws it as a button of its own, filled until done and outlined once done, as a profile's Follow and Following; style row draws it as a row of a List with style rows, the whole width, its label a row's words, joining the rows of a List or of row Actions right before it in a Stack with gap none, as Settings' Delete account after Sign out. confirm is a question asked first (\"Block @alice?\"), in a bundled view too; tone danger draws it in the danger colour (Block, Delete). leave true closes the screen it is on once it succeeds, as deleting the gallery shown; reload true reads the view again once it succeeds, as deleting a comment in it. signOut true signs the account out of the app once it succeeds, as deleting one's account (an Action with it draws only where the host signs out); handle binds the account's handle, which the person types to confirm (with confirm). A view that is not bundled asks the person to confirm, showing the record. Signed out, the first click asks the host to sign in. To write what a person types (a reply, a post), use Compose.",
notes: "A button that opens a form to write, as the signed-in account: a reply, a comment, a post, a gallery, an edit of a profile or a gallery. label is the button's words (and icon, count and closed as an Action's: a count drawn beside it, closed, as post.viewer.replyDisabled, drawing it as a Stat of its count; style button as an Action's, a profile's New gallery; style field as a field to write in, the whole width, holding its first text or line field's placeholder, else its label, as a photo app's \"Add a comment…\" under a post's comments); title and about head the form (\"Replying to dan\", the post's text); send is its button's word. form photo draws the form as a photo app's review of the one photo it takes, as Grain's new story: its first field, photos of max 1, its photo once picked full-bleed, a place field from it a chip over the photo's foot, the rest under it. fields, in order, each { name, kind, label?, required? } and by kind: text { placeholder?, max? (graphemes: the form holds the text to the lexicon of the record whose property it is, whole ({\"$value\": name}), its maxGraphemes and its maxLength in UTF-8 bytes; max only narrows those, and is needed where no lexicon limits it), facets? (links, #tags and @mentions highlighted, and made the record's facets), suggest? { method, service?, param, params?, items, did, handle, name?, avatar? }, the query whose answer suggests accounts as @ is typed, value? }; line { placeholder?, max? (as a text's), value? }; photos { min, max, alt, exif?, maxBytes, maxSide, value?, round? (drawn round, as an avatar), camera? (taking a photo with the device's camera offered beside picking one, as a story's; where it has none, picking) }, each uploaded as a blob, its value [{ blob, alt, aspectRatio, exif? }]; langs { max }; labels { options: [{ value, label }] }, its value [value]; choice { options: [{ label, value, only? }], multiple? }; place { from?, locate? } ({ name, value (an H3 cell), address }; from, a photos field, fills it from the place at its first located photo's GPS while none is picked, unless locate is false); card { from } (a link card of the text field from's first link: { uri, title, description, thumb? }). A field's value, a binding ({ \"$\": \"joins.profile.displayName\" }), is what it opens holding, as an edit's form: a text's words (also words joined, { \"$join\": [\"@\", { \"$\": \"author.handle\" }, \" \"] }, a reply's mention of whom it answers), a photo's picture (shown, and sent as nothing unless another is picked). A photos field's exif and a place's locate may be bindings too, an account's preference ({ \"$\": \"joins.prefs.preferences.@photoMetadataPref.includeExif\" }), on unless it holds false. given names values the view fixes, each a template of bindings ({ \"root\": { \"$first\": [{ \"$\": \"post.record.reply.root\" }, { \"$strongRef\": \"post\" }] } }, { \"rkey\": { \"$rkey\": \"response.gallery.uri\" } }). writes is what is written, all at once (apply_writes), each { collection, record, as?, each?, when?, whenItem?, rkey?, update? }: each makes one per element of an array value (photos), when names values that must be there, as names it for {\"$uri\": as} and {\"$rkey\": as}; update, a record key (self) or {\"$value\": name} holding one (a gallery's, given), replaces the one record there (a profile, a gallery): it is read first, {\"$stored\": path} reads it (its avatar's blob ref, as { \"$first\": [{ \"$value\": \"avatar.0.blob\" }, { \"$stored\": \"avatar\" }] }), and the fields the record names are set over it, those made of nothing taken out, the rest kept; where there is none yet, it is created. A record's values are literals or {\"$value\": name.path} (a field's or given value; an array's element by its index), {\"$item\": path} and {\"$index\": true} (in each or $each), {\"$each\": name, \"value\": …}, {\"$when\": [names], \"value\": …}, {\"$first\": […]}, {\"$merge\": […]}, {\"$stored\": path} (in an update), {\"$now\": true}, or {\"$facets\": key} (the facets of the text in the record's field key). What is not there is left out. Exactly one of writes, for and, in a bundled view alone, call ({ method, service, input }, as an Action's): the form's values are set on its input by their names, over the template's own (a report's reasonType and reason over its defaults), and the procedure called. for is the label of another Compose drawn in the same scope (not one of a List's items), whose form this one opens too, so a form is written once and offered twice, as a gallery's \"Add a comment…\" field under its comments opens the form of the Comment beside its favorites: it takes no fields, given, count, closed, icon, title, about, send or form of its own, its label its words ({ \"for\": \"Comment\", \"label\": \"Add a comment…\", \"style\": \"field\" }). signIn is the words drawn where the form can't be sent because no one is signed in and the app can sign someone in, which start signing in (\"Sign in to comment\"), in place of nothing. Sent, the view is drawn again.",
since: FIRST,
},
Component {
name: "Menu",
props: &[lit!("label", Ty::Short)],
children: true,
notes: "A ⋯ button that opens its children as a menu's rows, as an app's More over a profile or a post: each an Action (Mute, Block, a tone danger one red; with confirm, asked first), a Link (Copy link, Open in the app) or a Compose (Report), its row its label; a Stack among them gives its rows where its when, unless, mine or others holds (Delete on one's own gallery, Report on another's). label is the button's words read aloud (More, by default). A menu with no rows is not drawn.",
since: FIRST,
},
Component {
name: "Bar",
props: &[
lit!("title", Ty::Strings),
lit!("when", Ty::Path),
lit!("unless", Ty::Path),
lit!("when", Ty::Gate),
lit!("unless", Ty::Gate),
lit!("mine", Ty::Path),
lit!("others", Ty::Path),
],
children: true,
notes: "The screen's top bar: its title and buttons, as a photo app's \"Followers\" over a list of accounts, its gear on one's own profile and + over its feed. title is the screen's title, its words written one after another, each a string or a binding ([\"Followers\"], [\"#\", { \"$\": \"params.tag\" }], [{ \"$\": \"gallery.title\" }]), none where one of them resolves to nothing; the app draws it in its bar, as it draws its screens' titles. Its children are Links, Actions, Composes and Menus, each drawn as its icon alone (a Link's or Compose's icon; a Menu its ⋯), its label read aloud. Where the app has no bar it is drawn where it stands: its title a heading at the start of its row, its buttons at the end. One per screen, the first found among the Stacks at the top of its layout (its own first, or after a map that meets the bar; a feed's modes, each its own); when, unless, mine and others draw it as they do a Stack (mine: \"did\" on one's own profile alone). A bar of nothing is not drawn.",
since: FIRST,
},
Component {
name: "Panes",
props: &[],
children: true,
notes: "Panes one shown at a time, chosen by a row of icons over them, as a photo app's profile shows its galleries, favorites and stories: its children are Panes, each drawn only where its own when, unless, mine or others holds and it has something to show. With one pane, no row, but in a box wider than a phone's, where each icon has its word beside it (a desktop profile's Galleries over its grid); with none, nothing. A pane's Covers with select shows Select at the right end of the row.",
notes: "One of a Panes: its children, shown when its icon (or its label, read aloud) is chosen. when, unless, mine and others draw it as they do a Stack (mine: \"actor.did\" for one's own favorites).",
since: FIRST,
},
Component {
name: "Accounts",
props: &[],
children: true,
notes: "The accounts the app is signed in to, as its host keeps them, drawn by the host, as a photo app's Settings lists them: each a row of its picture, name and handle, the one in use ticked, another a tap from being the one in use, then Add account, which signs in to one more. Its children are drawn in its place where the host keeps no accounts (an MCP host): the account's own row, from the view's data. A bundled view's alone.",
notes: "A conversation, as a chat app draws one, and a layout's top node alone: its children are the template drawn in a bubble for each item, oldest at the top, the newest at the foot, scrolled to it (order newest-first for an answer that lists the latest first). from is the path within each item to its sender's DID: the signed-in person's own bubbles on the right, others' on the left beside their face and, among more than two people, their name, from people (an array of { did, handle, displayName?, avatar? }, as {\"$root\": \"response.relatedProfiles\"}); an item with no sender (a note of the conversation's own, as a member joined) is drawn centred, unframed. sent is the path to its time, under the last bubble of a run. The page's earlier items load at the top. empty is what it says with no items. send, in a bundled view alone, is a box to write in at the foot: what the person writes is sent as the procedure send calls (Action's call), the text where its input holds {\"$text\": true}, and the procedure's answer, an item, shows at the foot at once.",
since: FIRST,
},
];
@@ -1377,10 +1471,15 @@ pub fn to_json() -> Value {
"shape": "{ $type?: \"place.hud.view\", collection, description (one line), pageSize?: 1-100, origins?: [https origin], thumbnails?: [{ from, to }], list?: Mode, record?: Mode }, Mode = { join?: [Join or QueryJoin], summary?: Summary, layout: Node }; or, for a query's answers, { method, service: \"did:…#fragment\", description, query: { items?: path to the answer's array, cursor?: path to its cursor, join?: [QueryJoin], summary?: Summary, layout: Node } } (an answer that is one thing, as a thread, has no items: its scope's items and cursor are null, and layouts bind into response); unknown keys anywhere are refused; origins are the https origins whose URLs media props load, an inline view's only those a bundled view names (as https://cdn.bsky.app), and thumbnails rewrite a URL prefix on them to a smaller picture's; a method view's records is for bundled views alone: [{ collection, params: { <name>: literal | binding into the record's { uri, cid, did, value } }, at?: binding into it (what the answer shows first: a story in its archive), activity?: { verb, noun: [singular, plural], label?: binding } }], the collections whose records get_record draws as that query (a post as its thread), where no collection view draws them",
"modes": "list draws a page of records (list_records), record one record (get_record), query a query's answer (query; its summary runs over the items, or, with no items, over the scope, as a record's does); a mode left out is drawn generically",
"node": "{ component, props?, children? }: children only where the component takes them",
"node": "{ component, props?, children?, fallback? }: children only where the component takes them; fallback, on any component, a node drawn in its place by a kit that doesn't know it (a component or prop with since arrived in that HUD version: a kit, the renderer an app was built with, older than that draws a component it doesn't know as its children, else its fallback, else nothing, and ignores a prop it doesn't know; gate what it can't do without on the kit, a Stack's when { \"$kit\": \">=<since>\" })",
},
"scopes": {
"list": "{ did, handle, collection, records: [Rec], cursor, joins?: { <as>: answer | null } (its query joins': all of them on the first page, those that read records on every page) }",