Root
Components
Every component in the library, grouped by use, generated from the docs themselves.
Grouped by use, not by source layer: Forms, Actions, Navigation, Overlays & feedback, Data display, and Layout. Whole screens are not here — they live in Showcases.
This grid is generated from the page tree, so it cannot fall behind the docs: a component has a card here exactly when it has a page.
Forms
32Building a form, step by stepFrom one field to a complete form. Each step adds exactly one idea, and nothing is skipped.ControlsEvery form control in the library, grouped by what it captures. A table index — start here to find the right one.ValidationHow errors are displayed, who owns producing them, and why the library deliberately stops at the boundary.TanStack FormWiring TanStack Form and zod to Field — the setup, the validation modes, and the exact call for every control in the library.FieldThe chrome around a control — label, description, helper and error text, wired together — and the fieldset that groups several of them under one legend.Text inputsInput and Textarea — the two plain text controls, and the one attribute that styles both.EditableAn edit-in-place text field that swaps a preview for an input.CodeEditorA CodeMirror 6 host wired to the Kanzo tokens, with the language left to you.Tags InputA list of values the user invents, entered as removable chips — the one Choice control with no options to choose from.Input GroupAn input with adornments glued to its edges, sharing one border and focus ring.Native SelectThe browser's own select, styled to match the input scale.SelectA listbox of options in a popover, driven by an Ark collection.ListboxA list of selectable options with no popover of its own.ComboboxAn input that filters a list of options as you type.Language pickerA searchable picker for BCP 47 language tags, with each language named in its own language.Facet FilterThe one surface behind every faceted filter — a trigger that counts, a listbox of values, and a way out.Radio GroupA set of options where exactly one can be chosen.Segment GroupA segmented control — one of a few views, with a sliding indicator.CheckboxA binary control, with an indeterminate state.SwitchAn on/off toggle that applies immediately.Number InputA numeric input with stepper triggers, backed by the Ark machine.SliderA draggable value along a track, with one thumb or two.RatingRate something on a fixed scale of stars.DatesOne machine with a switch — the month grid inline, or the same grid in a popover.Color PickerPicks a colour from an area, channel sliders, swatches or the eyedropper.File UploadA dropzone and file list for selecting and previewing uploads.ImageCropperA box drawn on a photograph, and the photograph read back through it.Password InputA masked input with a reveal toggle.Pin InputA sequence of single-character cells for one-time passwords and verification codes.Field ArrayRepeatable rows — N controls, a remove per row, and one add below.QuestionA question put to the person, answered by picking — on its own, as a guided chat asks one per turn, or inside a Questionnaire.QuestionnaireA multi-step form that asks its questions one at a time, with progress, validation and navigation.
Actions
7ButtonTriggers an action or navigates, with a semantic variant and size scale.Button GroupA cluster of related actions rendered as one visual unit.ToggleA two-state button that stays pressed.Action BarA floating toolbar that rises when a selection exists.CommandA filterable command palette, inline or in a dialog.ClipboardA copy-to-clipboard control whose trigger flips to a check on copy.Download TriggerA trigger that serialises data to a file and downloads it on click.
Navigation
6BreadcrumbShows where a page sits in the hierarchy, and the way back up.TabsSwitches between panels of related content.LinkA token-styled anchor.StepsA stepper for a multi-stage flow, with per-step content and navigation.PaginationSplits a long list across pages and moves between them.SidebarThe provider and the parts — how a sidebar is assembled, and the full reference.
Overlays & feedback
10DialogA modal surface that interrupts the flow to ask for input or confirmation.PopoverA floating panel anchored to a trigger, for secondary controls that do not warrant a dialog.Hover CardA rich preview shown on hover — more than a tooltip can hold, less than a popover's commitment.TooltipA short label that appears on hover or focus, describing what a control does.MenuA dropdown list of actions, with groups, submenus and checkbox or radio selection.SheetA panel that slides in from an edge of the screen, for detail views and side forms.ToastA transient notification, created imperatively from anywhere in the app.TourA guided walkthrough that spotlights elements on the page, step by step.AlertAn inline message that needs attention but not a dialog.LoadingSpinner, Skeleton and Progress — three answers to one question, and which one your case is.
Data display
21TableThe presentational table primitive — semantic elements, tokenised chrome, no data layer.Data TableA thin composable layer over TanStack Table — the parts a connected table is assembled from.StatOne dashboard number — a label, the figure, a signed delta, a sparkline and a status, as a card you can make a link.Tree ViewA keyboard-navigable hierarchy of branches and leaves.JSON Tree ViewAn expandable, syntax-coloured tree view of any JSON value.CardA bordered surface for grouping related content.ItemThe row counterpart to Card — a media · content · actions strip for lists.DataListA record read back — label and value, as a real `<dl>`.DiagnosticA severity, a message, and the positions it points at — collapsible, and jumpable.ProblemAnything a catch holds, shown as a Diagnostic — its code, its title, its causes as a tree, and the host's words over the library's.FindingsWhat a check found — one result or many sharing a rule — as items, grouped under a heading, behind a badge that tallies them and a header that says what was checked.StatusA small coloured dot for a live state.SwatchA colour, drawn — decoration beside the text that names it.BadgeA compact status or category label.AvatarA user or entity image with a text fallback, a presence badge, and a stacked group.ProgressShows how far along a determinate — or indeterminate — task is.FormatByte sizes, numbers and relative dates, formatted by Intl in the page's locale.ProseStyles a block of rendered long-form content — markdown, a changelog, an article.KbdRenders a keyboard key in running text.EyebrowThe small uppercase line that names a block from above it.HighlightWraps matching substrings of running text in a token-themed mark.
Analytics
6ChartsA thin composable layer over Mosaic/vgplot — marks, interactors and axes as JSX, over a bring-your-own DuckDB coordinator.Chart gallerySixteen chart types written with the charts grammar — each one a ChartRoot and a handful of marks, none of them a component.DashboardA dashboard over any relation for finding what it holds — a filter bar and tiles (figures, charts, tables), chosen from the relation's stats, edited where they sit, and kept as a JSON spec the host saves.Dashboard specThe JSON a Dashboard is drawn from and hands back on every edit — every field, what it accepts, how an invalid one is treated, how a host keys it by relation, and the one way to read it back.Host recipeWiring a Dashboard to a backend — loading a saved spec, writing it after a pause, a read-only mode, your own labels and colours, one dashboard per relation, and where failures go.PitfallsThe failures on the analytics subpath that point somewhere other than their cause — what each looks like, why it happens, and what to do instead.
Graph
3Layout and cameraThe data's status and the layout's motion, when the GPU layout runs and how it scales, what a drag does to the points, when the camera follows, and what is kept when the canvas goes.Discovery workspaceA recipe — the engine, a graph attached by name, and the graph parts and charts on one crossfilter.BenchmarksOur viewer against cosmos.gl alone on the same positions, how far cosmos.gl's live layout goes, and where the layout's tuning was measured.
AI
6AssistA field the model helps fill. One proposal for the field's value, drawn the way the control calls for — ghost text at the caret of a Textarea, whole values under an Input, items for a TagsInput.ChatA conversation with a model, whole — the transcript, markdown that streams, the model's reasoning and tool calls as they happen, and a composer that sends, stops and retries. The host brings the conversation (useAgentChat) and draws its own tools' results.A guided chatThe parts a conversation whose turns the host decides is built from, beside the transcript and the composer — work under way, a model in the page as it loads, a point to go back to, the steps of the work, the sources a thread rests on and the ones a message carries — and the question it puts to the person, which is @kanzo-tech/ui's.Ask your dataAsk — questions about data answered with a dashboard tile over a relation, from a spec the model fills with paths the page generated, resolved by the page's joins — the types it may answer about, the chat it runs in, the questions to start from, and the card each answer is drawn in — @kanzo-tech/ai/data.TasksA small model fills a small artefact under a JSON Schema, oracles check it, and a bounded loop repairs it or asks the person — defineTask, runTask, propose, verify from @kanzo-tech/ai/task, and useTask for a screen's list of proposals.@kanzo-tech/llmThe two doors to a model's answer, without React — stream and generate, each asking once over the AI SDK, which it does not re-export; localModel, a model that runs in the page; and the one model double.
Auth
6SessionOne session shape, read on the server from the token the edge forwards and handed to the browser as a prop; signing in and out at the edge; and why the current organization is resolved per request rather than stored.Rolescan, Gate and useSession().can — asking a role question inside the current organization, where the roles in it are read from, and why the predicate has no hierarchy.KeycloakThe realm this package expects — role claims on the access token, each API a client whose scope puts it in aud, the organization scope with the star, an application's roles inside each organization, a sign-out at Keycloak, and passkeys.The identity serviceThe server half of @kanzo-tech/auth — Keycloak with the platform realm as code, applied from what applications and organizations declare, and a script that checks the claim contract on a live token.ServersessionReader — the access token the platform's edge forwards, verified against the realm's keys and read into one Session, framework-agnostic; and claims, the reader underneath it.Next.jsAn App Router product behind the platform's edge as one object — kanzoAuth, whose session() a server component reads from the forwarded token, whose proxy forwards the URL and the CSP nonce, and whose api forwards to the application's resource servers.
Navigation guard
1Testing
2Writing a harnessA harness for a part of your own — extending ComponentHarness, finding its host and its insides by their ARIA, composing the library's harnesses inside it, and waiting on states.Organising an end-to-end suiteHow a host's Playwright suite is layered over the library's harnesses — specs over page objects over harnesses — and the rules that keep it from flaking, after Playwright's own best practices.
Layout
15ShellThe window regions — root, header, body, aside, main, footer. Structure only, no aesthetic.Skip NavThe "skip to main content" link, and the main landmark it lands on.SectionContent scaffolding — a heading with optional icon, supporting text and actions, over a body and a footer.EmptyThe zero state of a region — an indicator, a title, a sentence and what to do next, centred.GatedA region shown but not yet usable — dimmed, out of reach, and announced by the reason pinned to its corner.ResizablePanels the user can resize by dragging the divider between them.Scroll AreaA scrollable region with overlay scrollbars that appear only while in use.Floating panelA surface floating over a canvas, with a drag edge — an example to copy, not a component.RenderingShow and ClientOnly — the two control-flow helpers that produce no DOM of their own.SeparatorA visual or semantic divider.MadeWithA "Made with ♥ at …" attribution line, styled once.FloatPositions a child over a corner or edge of its positioned ancestor.AccordionA stack of headings that each reveal a region of content.CollapsibleA region that animates its height open and closed.PreferencesEvery preference a person may change — the theme for each side, the side, density, and what installed packages contribute — and nothing a theme owns.
Hooks
15useKanzoThemeRead and write the runtime theme preferences owned by KanzoThemeProvider.useIsMobileA boolean that tracks whether the viewport is below the md breakpoint.useAsyncCollectionItems fetched as the user types — a debounced query, a request that aborts when a newer one starts, and the loading, empty and error states of the last one.useDebouncedCommitA control that keeps what is being typed to itself and tells its owner once typing pauses.useSidebarRead and drive the sidebar's open state from anywhere below SidebarProvider.useTourContextReach the tour instance and its start handler from any control inside a Tour.useChartContextThe chart context — config, selections, engine, and the color / formatNumber helpers — for a DOM part of your own inside a ChartRoot.useChartContextOptionalThe chart context or null — for a part that has to work both inside a ChartRoot and standalone.useChartCapacityHow many categorical slots the live theme publishes, read off the cascade and re-read when the theme moves.useChartQueryRead a relation from the same coordinator the charts use, under the same crossfilter — for anything that is not a plot.useQueryRowsA statement's rows on the page's engine, suspending until they land — for what a page reads once, outside the crossfilter.useThemeTickRe-render when the theme changes, so a surface painted from resolved tokens repaints instead of freezing the theme it mounted with.useMosaicThe Mosaic context in one call — the engine, the page's one selection and the joins its relations are read over.useDataTableThe engine behind DataTable — every TanStack row model wired, the state slices held for you, the instance handed back.useDataTableContextThe table instance of the enclosing DataTableRoot, typed by your row type — so a part of your own is a component like any other.
The design of Kanzo UI
28Why the library is like this, what was measured, and what would reverse each of it.
The layers, and the one rule at each seamFive layers with imports pointing down, a dependency-free kernel at the bottom, one rule for each place two packages meet, and the guards that make the direction a test instead of a sentence.The kernelThe one dependency-free package every other package may import, and what it holds, what it refuses to hold, and what each of its five pieces replaced; with the rule that holds the direction.The engineWhy every package reaches DuckDB through one read-only port and one door, why aborting a query interrupts the statement, why a dying engine is a supported state, and why the library redacts what it throws; and what would reverse each rule.RelationsWhy JoinGraph is the one read-model of a catalog, why a typed CatalogReader is the only way one is made, how a mapping fills what a catalog does not say and where that match is fragile, why a path reads as Malloy's dots and SPARQL's inverse, and why the shape before a run comes from the compiler; and what would reverse each rule.What earns a nameThe rules that decide whether something becomes a component at all — the taxonomy test, the second call site, the layers that ship code and the ones that ship a guide.The references, and who winsThe case law under one sentence — Ark owns behaviour, Shark owns surface, AI Elements is a source and not a reference, and a measurement overrules all of them.Names and slotsWho owns `data-slot`, what may never be keyed on it, and the two collisions that decided a rename.The colour documentWhy a theme is a flat block of CSS with one mode, how a tint is written, what a section is, and what each would take to reverse.Preference or themeOne rule decides whether a value is the person's or the brand's. The declaration lists only preferences, so a value the theme owns never gets a control.The graph viewHow @kanzo-tech/graph is built — one Mosaic client on the page's coordinator over an Apache GraphAr graph @kanzo-tech/graphar-duckdb attached, uploaded to cosmos.gl once and greyed out by the crossfilter, a scale limit that is guarded and raised only by measurement, a canvas a keyboard and a screen reader can use, an Ark-shaped root over flat parts — and what would reverse each rule.Hardening the graph viewWhat @kanzo-tech/graph does so that a graph too large to draw exactly, a failed read, a lost WebGL context, a large pick or a person without a pointer or sight does not become a wrong picture, a dead canvas or an inaccessible one.AnalyticsHow the dashboard is built — Mosaic's public surface and nothing under it, a spec that is read whole or refused, a recommender made of Show Me's cases, three tables over one closed set of kinds, and an editor nobody downloads until they edit — and what would reverse each rule.TimelineWhy a time filter is a histogram whose brush owns its clause and sticks to its bars, why play runs inside the brushed range, accumulating, through the brush's own clause and at the page's pace, why its window reaches the page as identity and greys what has no time, why time is read from the schema and never guessed, and why a date on a relation is a vertex — and what would reverse each rule.CrossfilterWhy everything that narrows the page is a filter — one clause on one page selection, the timeline and the canvas included — why "kept" is decided once and only drawn differently per view, why a position is an encoding and "no position" a state of its own, and what that changes in the graph, the timeline and the gestures.One read per datumWhy every read the library makes for a host — a relation's fields, an answer's rows — is a TanStack Query query inside the library's own hook, on the host's QueryClient, with no queryOptions surface; and what would reverse it.What a field isWhy a field's facts come from the data's own catalog — what it is from what the catalog declares, what it holds from counts where something counted it — and reach every reader through JoinGraph, so nothing in the library guesses them from a column's name or a threshold; and what would reverse each part.Asking dataWhy an answer in @kanzo-tech/ai/data is a tile over a relation the model fills from typed names, not SQL it writes; why the model is open and remote models are a non-goal; what no default sends out of the page; how a call is set, bounded and scored; and what would reverse each.Asking within a contextWhy @kanzo-tech/ai/data describes each type once, why the answer's schema names a field list once, and why the linker, not a token count, keeps a question inside a small model's context — measured on five graphs, and what would reverse each.TasksWhy Ask and Fossil's assistant become one pattern — a small model fills a small artefact under contract, a deterministic oracle checks it, and a bounded loop repairs it or asks the person — and what would reverse each part.The servicesWhy a capability's server half ships beside its client half, in one repository under one tag; why Compose is the whole of it; and why the service names no application and carries no production configuration.The auth layerWhy authentication is a sibling package rather than a component, why the relying party is the platform's oauth2-proxy and not this package, why a browser draws instead of deciding, and why the forwarded token is verified on every read.How the auth layer failsWhy a failure is not a signed-out person, why the session arrives with the page, why every refusal is a problem body, why a failure at a required session is the problem page, and why one party bounds each wait; and what would reverse each rule.Hardening the auth layerWhat @kanzo-tech/auth does so that a script on the origin, a hung API, a request with no origin or a forged header does not become an API call; what moved to the platform's edge; the one session reader; the realm baseline; and the limits it states instead of fixing, each with what would reverse it.The navigation layerWhy the unsaved-changes guard is a sibling package, why it copies TanStack Router's shape, why Next needs a door of its own, why nothing in it patches history, and why a route's sidebar intent is not the person's preference.The shell's dockWhy a page switches its side panels with one part, an activity bar of icons named by their tooltips — and what would reverse it.How a failure leaves the libraryOne failure class in RFC 9457's shape, thrown whole; a registry of codes generated from one source; and every wait bounded once, with the inner deadline expiring before the outer. The argument across fossil, kanzo-ui and their hosts is fossil's page, not this one.FindingsWhy a finding is always one result and a group is many but both are one item with one action, why its place is the host's and reaches the library only through describe, why an item's message wraps on a line of its own, why the header is parts, and why the entry is a badge that opens a popover — and what would reverse each rule.Testing a page built with Kanzo UIWhy @kanzo-tech/testing ships a harness per component in Angular CDK's shape and with its names, reads ARIA before anything else, reads a canvas's coordinates off the element it drew, and registers the one model double as a provider in the registry every model is resolved through; why a test reads from one real engine and a model's test replays a recording; and why Ask's evaluation set lives beside Ask — and what would reverse each rule.