# Koten UI — full documentation > Generated from the catalog and internal guides. Prefer the per-page Markdown when you need one component; use this file to load the whole system. Japanese labels in the documentation are internal styling; do not add Japanese text or decoration to a consumer UI unless requested (R-031, D-057). --- --- title: "Accordion" description: "Groups secondary content into sections that open and close. It can keep a single section open or several at once." kind: component id: C-030 registry: "accordion" docs: "https://koten.codehive.com.co/components/accordion" markdown: "https://koten.codehive.com.co/md/components/accordion.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/accordion.json" language: en --- # Accordion · アコーディオン > Component C-030 in the Koten UI catalog. Groups secondary content into sections that open and close. It can keep a single section open or several at once. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/accordion.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/accordion.json ``` ## Files - `@/components/ui/accordion.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Reference - Upstream primitive: https://base-ui.com/react/components/accordion ## Examples ### One section at a time defaultValue opens shipping; opening another section closes the previous one. ```tsx ``` ### Several sections multiple keeps shipping and returns open at the same time. ```tsx ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `items` | `AccordionItem[]` | `—` | Each item defines value, title, content and an optional disabled. | | `defaultValue` | `string \| string[]` | `—` | Section or sections open on mount. | | `value` | `string \| string[]` | `—` | Controlled value; use an array when multiple is enabled. | | `onValueChange` | `(value: string \| string[]) => void` | `—` | Returns string or string[] depending on multiple. | | `multiple` | `boolean` | `false` | Allows several sections to be open at once. | | `className` | `string` | `—` | Applied to the container; borders separate the sections. | ## Accessibility - Each trigger is a button inside a header and exposes aria-expanded and aria-controls. - Focus stays on the trigger after opening or closing. - The chevron rotates and the title changes color, so the state does not rely on a single cue. - The closed panel is hidden from screen readers; the trigger communicates the state. ## Sources - Catalog page: https://koten.codehive.com.co/components/accordion - Markdown: https://koten.codehive.com.co/md/components/accordion.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "Alert" description: "Communicates the outcome of an action or a system risk. The tone declares urgency; the text explains what happened and, when needed, what to do next." kind: component id: C-018 registry: "alert" docs: "https://koten.codehive.com.co/components/alert" markdown: "https://koten.codehive.com.co/md/components/alert.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/alert.json" language: en --- # Alert · 通知 > Component C-018 in the Koten UI catalog. Communicates the outcome of an action or a system risk. The tone declares urgency; the text explains what happened and, when needed, what to do next. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/alert.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/alert.json ``` ## Files - `@/components/ui/alert.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Examples ### Tones info and success confirm without interrupting; the tone picks the icon and the left border. ```tsx
The order will leave the Tokyo warehouse. Your changes were saved successfully.
``` ### Urgency and action warning and danger announce immediately; action adds a way out without competing with the text. ```tsx Review} > 3 units of HIKARI K-1 left. The payment could not be processed. ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `tone` | `info \| success \| warning \| danger` | `info` | info and success use role status; warning and danger use role alert. | | `title` | `ReactNode` | `—` | Visible heading and name of the notice; without it the body must stand on its own. | | `icon` | `ReactNode` | `—` | Replaces the tone icon; it must remain decorative (aria-hidden). | | `action` | `ReactNode` | `—` | Action at the end of the notice; use Button size xs with the outline variant. | | `div props` | `ComponentProps<"div">` | `—` | Forwarded to the container; do not override role without a semantic reason. | ## Accessibility - info and success use role status; warning and danger use role alert. The tone decides the announcement, not the color. - The visible title names the notice and is read together with the body. - The icon is aria-hidden: meaning lives in the text and the tone. - The action keeps its own accessible name, and focus reaches it after the message. ## Sources - Catalog page: https://koten.codehive.com.co/components/alert - Markdown: https://koten.codehive.com.co/md/components/alert.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "Badge" description: "A short metadata label for states, counts and tags. Tone supplies color and appearance controls weight; the text always carries the meaning." kind: component id: C-003 registry: "badge" docs: "https://koten.codehive.com.co/components/badge" markdown: "https://koten.codehive.com.co/md/components/badge.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/badge.json" language: en --- # Badge · 印 > Component C-003 in the Koten UI catalog. A short metadata label for states, counts and tags. Tone supplies color and appearance controls weight; the text always carries the meaning. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/badge.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/badge.json ``` ## Files - `@/components/ui/badge.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Examples ### Tones Seven tones in the default soft appearance; sale and new are fixed across themes. ```tsx Neutral Info In stock Low stock Cancelled Sale New ``` ### Appearances soft uses the tone border and text, solid inverts the background and outline leaves it transparent. ```tsx In stock In stock In stock ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `tone` | `neutral \| info \| success \| warning \| danger \| sale \| new` | `neutral` | sale always uses shu and new always ai, regardless of theme; the rest follow the theme roles. | | `appearance` | `soft \| solid \| outline` | `soft` | solid uses the tone as background with text-solid-fg on top; outline paints no background. | | `dot` | `boolean` | `false` | Adds a decorative dot with aria-hidden; it never replaces the text. | ## Accessibility - State is never conveyed by color alone: there is always visible text. - The dot is decorative and carries aria-hidden, so it does not duplicate information. - Badge uses text-2xs as metadata; do not use it for paragraphs or primary content. - Text tones meet AA on paper and surface according to the token test. ## Sources - Catalog page: https://koten.codehive.com.co/components/badge - Markdown: https://koten.codehive.com.co/md/components/badge.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "BarChart" description: "A decorative bar chart with labels and an sr-only table that repeats the data. Each bar's height is proportional to the maximum; color and weight come from tokens." kind: component id: C-066 registry: "bar-chart" docs: "https://koten.codehive.com.co/components/bar-chart" markdown: "https://koten.codehive.com.co/md/components/bar-chart.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/bar-chart.json" language: en --- # BarChart · 棒グラフ > Component C-066 in the Koten UI catalog. A decorative bar chart with labels and an sr-only table that repeats the data. Each bar's height is proportional to the maximum; color and weight come from tokens. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/bar-chart.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/bar-chart.json ``` ## Files - `@/components/ui/bar-chart.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Requirements - **provider** — KotenProvider: useKoten picks the sr-only table headers (Label/Value) and the locale used to announce the data. ## Examples ### Daily series Decorative bars and an sr-only table with the same information. ```tsx const data = [ { label: "Lun", value: 42 }, { label: "Mar", value: 58 }, { label: "Mié", value: 36 }, { label: "Jue", value: 71 }, { label: "Vie", value: 64 }, { label: "Sáb", value: 28 }, { label: "Dom", value: 19 }, ]; `${formatNumber(value)} pedidos`} /> ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `data` | `readonly BarChartDatum[]` | `—` | Each point is { label, value }; the label also heads the accessible table row. | | `label` | `string` | `—` | Visible title and caption of the sr-only table. | | `height` | `number` | `160` | Height of the bar area in px; labels sit outside it. | | `formatValue` | `(value: number) => string` | `String(value)` | Formats the accessible table value and the title of each bar. | | `className` | `string` | `—` | Classes for the figure; width adapts to the container. | ## Accessibility - Bars and visual labels are aria-hidden; the information lives in an sr-only table with a caption. - The fallback table translates its headers according to the KotenProvider locale. - formatValue should include the unit; without it the accessible table loses context. ## Sources - Catalog page: https://koten.codehive.com.co/components/bar-chart - Markdown: https://koten.codehive.com.co/md/components/bar-chart.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "Breadcrumb" description: "Shows the hierarchical path to the current page. The last item is marked as current while the earlier ones stay navigable." kind: component id: C-027 registry: "breadcrumb" docs: "https://koten.codehive.com.co/components/breadcrumb" markdown: "https://koten.codehive.com.co/md/components/breadcrumb.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/breadcrumb.json" language: en --- # Breadcrumb · パンくず > Component C-027 in the Koten UI catalog. Shows the hierarchical path to the current page. The last item is marked as current while the earlier ones stay navigable. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/breadcrumb.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/breadcrumb.json ``` ## Files - `@/components/ui/breadcrumb.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Examples ### Default path The last item needs no href: it renders as text and receives aria-current=page. ```tsx ``` ### Custom separator separator accepts any ReactNode; it stays decorative and outside the focus order. ```tsx ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `items` | `{ label, href?, current? }[]` | `—` | The last item is current when no item declares it. | | `label` | `string` | `—` | Accessible name of the nav; applied as aria-label. | | `separator` | `ReactNode` | `"/"` | Decorative; hidden from screen readers. | | `onNavigate` | `(href: string) => void` | `—` | Receives plain clicks on items with href; useful for a router. | | `className` | `string` | `—` | Applied to the wrapping nav. | ## Accessibility - The nav takes its aria-label from label, so it is distinct from other navigation landmarks. - The list uses ol and li; the last item receives aria-current="page". - Separators are decorative: aria-hidden and outside the focus order. - onNavigate only intercepts plain clicks; modified clicks keep the browser behavior. ## Sources - Catalog page: https://koten.codehive.com.co/components/breadcrumb - Markdown: https://koten.codehive.com.co/md/components/breadcrumb.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "Button" description: "The primary action of the system. The theme decides the color; the button only declares a semantic variant and a size." kind: component id: C-001 registry: "button" docs: "https://koten.codehive.com.co/components/button" markdown: "https://koten.codehive.com.co/md/components/button.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/button.json" language: en --- # Button · ボタン > Component C-001 in the Koten UI catalog. The primary action of the system. The theme decides the color; the button only declares a semantic variant and a size. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/button.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/button.json ``` ## Files - `@/components/ui/button.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Examples ### Variants Six semantic roles: secondary, primary, outline, ghost, danger and link. ```tsx ``` ### Sizes and states Height comes from density; size adjusts text and padding. ```tsx ``` ### Composition with render For navigation use a link with buttonVariants or render; never a button that changes routes. ```tsx Documentation ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `variant` | `primary \| secondary \| outline \| ghost \| danger \| link` | `secondary` | The color is decided by the theme, not the component. | | `size` | `xs \| sm \| md \| lg` | `md` | Height comes from --koten-control-h; size adjusts text and padding. | | `loading` | `boolean` | `false` | Adds a spinner, aria-busy and disabled. | | `nativeButton` | `boolean` | `true` | Pass false when render draws a link or another element. | | `render` | `ReactElement \| function` | `—` | Base UI composition, without asChild. | ## Accessibility - The accessible name comes from visible content; for an icon-only button, aria-label is required. - loading disables the button and announces aria-busy; it does not change the layout. - For navigation use an with buttonVariants, not a ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `label` | `ReactNode` | `—` | Visible content and accessible name; required. | | `description` | `ReactNode` | `—` | Renders under the label, outside the accessible name. | | `checked / defaultChecked` | `boolean` | `false` | Controlled or uncontrolled. | | `indeterminate` | `boolean` | `false` | Shows a dash and is announced as mixed; it does not change checked. | | `onCheckedChange` | `(checked: boolean, event: Event) => void` | `—` | Fires when the box is checked or unchecked. | | `disabled` | `boolean` | `false` | Blocks the control and excludes it from submission. | | `name` | `string` | `—` | Name the value travels with in the form. | ## Accessibility - The label wraps Base UI's real control, so the accessible name comes from the visible text. - description renders outside the label so the accessible name stays short. - indeterminate is announced as mixed and does not replace checked. - Visible focus uses a 2 px outline with an offset, never outline: none. ## Sources - Catalog page: https://koten.codehive.com.co/components/checkbox - Markdown: https://koten.codehive.com.co/md/components/checkbox.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "Combobox" description: "A text input with incremental filtering and single-option selection. Items are strings, and the empty and trigger labels are required." kind: component id: C-010 registry: "combobox" docs: "https://koten.codehive.com.co/components/combobox" markdown: "https://koten.codehive.com.co/md/components/combobox.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/combobox.json" language: en --- # Combobox · 検索選択 > Component C-010 in the Koten UI catalog. A text input with incremental filtering and single-option selection. Items are strings, and the empty and trigger labels are required. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/combobox.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/combobox.json ``` ## Files - `@/components/ui/combobox.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Reference - Upstream primitive: https://base-ui.com/react/components/combobox ## Examples ### Search and states emptyLabel covers the no-match case and triggerLabel names the icon-only button. ```tsx ``` ### Controlled selection onValueChange returns the chosen string or null, with no intermediate objects. ```tsx const [customer, setCustomer] = useState("HIKARI Store");

Selected: {customer ?? "none"}

``` ### Use inside a form Combobox has no help or error props; both are composed below with the same tokens, and the error uses role=alert. ```tsx
event.preventDefault()} >

Billing and delivery addresses follow the customer record.

Pick an existing customer before saving.

``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `label` | `string` | `—` | Visible label linked to the input through htmlFor/id; required. | | `items` | `readonly string[]` | `—` | Strings; the input filters by match while typing. | | `emptyLabel` | `string` | `—` | Visible message when no item matches. | | `triggerLabel` | `string` | `—` | aria-label of the icon-only button that opens the list. | | `placeholder` | `string` | `Buscar…` | Input text shown when it is empty. | | `value / defaultValue` | `string` | `—` | Controlled or uncontrolled. | | `onValueChange` | `(value: string \| null) => void` | `—` | Returns the chosen string, or null when the selection is cleared. | | `disabled / name` | `boolean / string` | `false / —` | name submits the value with the form; disabled blocks the input and the trigger. | ## Accessibility - The input is labelled through htmlFor/id, and the icon trigger carries triggerLabel as its aria-label. - Filtering happens while typing; emptyLabel provides the visible message when nothing matches. - Escape closes the popup and keeps the typed text so it can be corrected. ## Sources - Catalog page: https://koten.codehive.com.co/components/combobox - Markdown: https://koten.codehive.com.co/md/components/combobox.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "CommandPalette" description: "Keyboard-first global search: type to filter, arrows to move, Enter to run and Escape to close. Focus always returns to the trigger." kind: component id: C-065 registry: "command-palette" docs: "https://koten.codehive.com.co/components/command-palette" markdown: "https://koten.codehive.com.co/md/components/command-palette.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/command-palette.json" language: en --- # CommandPalette · コマンド > Component C-065 in the Koten UI catalog. Keyboard-first global search: type to filter, arrows to move, Enter to run and Escape to close. Focus always returns to the trigger. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/command-palette.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/command-palette.json ``` ## Files - `@/components/ui/command-palette.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Requirements - **portal** — Portaled popup: The palette mounts in BaseDialog.Portal. Do not nest it in containers with overflow or transform, because the backdrop must cover the window. - **controlled** — Controlled state (open / onOpenChange): The palette does not open by itself: it takes open and onOpenChange, and you own the state. When it closes with Escape or on select, focus returns to the trigger. ## Reference - Upstream primitive: https://base-ui.com/react/components/dialog ## Examples ### Opening from a button Four grouped commands; the chosen result is announced next to the trigger. ```tsx const [open, setOpen] = useState(false); runCommand(item.id)} /> ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `open` | `boolean` | `—` | Controls visibility; the palette holds no internal open state. | | `onOpenChange` | `(open: boolean) => void` | `—` | Called on close via Escape, the backdrop or an item selection. | | `label` | `string` | `—` | Accessible name for the dialog, the field and the list. | | `placeholder` | `string` | `—` | Hint text inside the search field. | | `emptyLabel` | `string` | `—` | Visible message when no item matches. | | `items` | `readonly CommandItem[]` | `—` | id, label, description, group, keywords, icon and shortcut. | | `onSelect` | `(item: CommandItem) => void` | `—` | Called after closing; focus has already returned to the trigger. | | `hint` | `ReactNode` | `—` | Keyboard hint at the bottom; the component ships no internal strings. | | `className` | `string` | `—` | Merged with the popup max width and border. | ## Accessibility - The field is a combobox with aria-controls, aria-autocomplete and aria-activedescendant; the list is a listbox. - The dialog traps focus and returns it to the trigger on close, including with Escape. - Arrows, Home/End and PageUp/PageDown move; Enter runs the active command. - The empty state and the chosen result are conveyed as text, not only with colour. ## Sources - Catalog page: https://koten.codehive.com.co/components/command-palette - Markdown: https://koten.codehive.com.co/md/components/command-palette.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "DataTable" description: "A data table on TanStack Table with sorting, selection and pagination in client state. It keeps the identity of data, accepts custom-rendered columns and can virtualize thousands of rows without changing the table semantics." kind: component id: C-038 registry: "data-table" docs: "https://koten.codehive.com.co/components/data-table" markdown: "https://koten.codehive.com.co/md/components/data-table.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/data-table.json" language: en --- # DataTable · データ表 > Component C-038 in the Koten UI catalog. A data table on TanStack Table with sorting, selection and pagination in client state. It keeps the identity of data, accepts custom-rendered columns and can virtualize thousands of rows without changing the table semantics. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/data-table.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/data-table.json ``` ## Files - `@/components/ui/data-table.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Requirements - **dependency** — @tanstack/react-table: The component imports useReactTable, getCoreRowModel, getSortedRowModel and getPaginationRowModel. The registry item declares the npm dependency; install it before copying the file. - **client** — Client state: sort, selection and pagination: sorting, rowSelection and the page live in local state. Keep the identity of data across renders: a fresh copy resets pagination. ## Reference - Upstream primitive: https://tanstack.com/table/latest ## Examples ### Sort, selection and pagination Ten orders, five per page; state lives on the client and selection is announced. ```tsx const columns: DataTableColumn[] = [ { id: "id", header: "Pedido", cell: (row) => {row.id}, sortValue: (row) => row.id, sortable: true, }, { id: "customer", header: "Cliente", cell: (row) => row.customer }, { id: "state", header: "Estado", cell: (row) => ( {stateLabels[row.state]} ), }, { id: "total", header: "Total", cell: (row) => formatCurrency(row.total), sortValue: (row) => row.total, sortable: true, align: "right", }, ]; row.id} caption="Pedidos KURA" emptyLabel="Sin pedidos para los filtros." previousLabel="Anterior" nextLabel="Siguiente" paginationLabel="Paginación de pedidos" selectAllLabel="Seleccionar todos los pedidos de la página" selectRowLabel={(id) => `Seleccionar ${id}`} selectedLabel={(count) => `${count} pedidos seleccionados`} selectable pageSize={5} /> ``` ### 10,000 virtualized rows Only the visible window plus overscan is mounted; the header stays sticky and the table keeps aria-rowcount/aria-rowindex. ```tsx const rows = Array.from({ length: 10_000 }, (_, index) => ({ id: `KURA-${String(index + 1).padStart(5, "0")}`, total: 4800 + (index % 97) * 310, })); row.id }, { id: "total", header: "Total", cell: (row) => formatCurrency(row.total), align: "right" }, ]} getRowId={(row) => row.id} caption="Pedidos KURA" emptyLabel="Sin pedidos para los filtros." previousLabel="Anterior" nextLabel="Siguiente" paginationLabel="Paginación de pedidos" selectAllLabel="Seleccionar todos los pedidos de la página" selectRowLabel={(id) => `Seleccionar ${id}`} selectedLabel={(count) => `${count} pedidos seleccionados`} virtualized height={320} rowHeight={32} /> ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `data` | `readonly T[]` | `—` | Keep the array identity across renders or pagination resets. | | `columns` | `readonly DataTableColumn[]` | `—` | Each column defines header, cell and, when needed, sortValue, sortable and align. | | `getRowId` | `(row: T) => string` | `—` | Stable row ID; it also identifies selection and the aria-live announcement. | | `selectable` | `boolean` | `false` | Adds a per-row checkbox, page selection and an aria-live count. | | `onSelectionChange` | `(ids: string[]) => void` | `—` | Receives the selected IDs; selection state still belongs to the client. | | `pageSize` | `number` | `8` | Rows per page; with virtualized, pagination is ignored. | | `virtualized` | `boolean` | `false` | Renders only the visible window and disables pagination. | | `height` | `number` | `480` | Height of the virtualized container in px. | | `rowHeight` | `number` | `36` | Fixed row height; it must match the active density. | | `loading` | `boolean` | `false` | Shows three skeleton rows instead of the data. | | `emptyLabel` | `string` | `—` | Text for the empty row; required so the empty state is explicit. | ## Accessibility - Sortable headers are real buttons and expose aria-sort as ascending, descending or none. - Selection uses a per-row checkbox with aria-label and announces the count in an aria-live region. - The virtualized table keeps aria-rowcount and aria-rowindex, and its container is focusable. - Numbers are right-aligned and use tabular-nums. ## Sources - Catalog page: https://koten.codehive.com.co/components/data-table - Markdown: https://koten.codehive.com.co/md/components/data-table.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "DatePicker" description: "A date field with an anchored panel, not portalled. It covers single dates and ranges, formats with Intl and returns Date through onValueChange; the application stores ISO 8601 and converts it at render time." kind: component id: C-064 registry: "date-picker" docs: "https://koten.codehive.com.co/components/date-picker" markdown: "https://koten.codehive.com.co/md/components/date-picker.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/date-picker.json" language: en --- # DatePicker · 日付選択 > Component C-064 in the Koten UI catalog. A date field with an anchored panel, not portalled. It covers single dates and ranges, formats with Intl and returns Date through onValueChange; the application stores ISO 8601 and converts it at render time. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/date-picker.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/date-picker.json ``` ## Files - `@/components/ui/date-picker.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Requirements - **provider** — KotenProvider: useKoten supplies the panel labels and the locale; useKotenFormatters formats the visible value and the calendar days. - **controlled** — Controlled value (ISO 8601): Store the date as ISO in your state, convert it to Date for value and back to ISO in onValueChange. value and onValueChange are the single source of truth. ## Examples ### Controlled value (ISO) The application state stores ISO 8601 and the field converts it to Date. ```tsx const toIso = (date: Date) => `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`; const [iso, setIso] = useState("2026-10-21"); const value = iso ? new Date(`${iso}T00:00:00`) : null; setIso(next ? toIso(next) : "")} min={new Date(2026, 9, 1)} max={new Date(2026, 11, 31)} defaultMonth={new Date(2026, 9, 1)} /> ``` ### Range Start and end in a single field; the panel is anchored to the button. ```tsx const [range, setRange] = useState({ start: new Date(2026, 9, 21), end: new Date(2026, 9, 27), }); ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `mode` | `"single" \| "range"` | `"single"` | In range mode, value is a DateRange and the panel expects two clicks. | | `value` | `Date \| DateRange \| null` | `—` | Controlled value; Date in single mode and { start, end } in range mode. | | `defaultValue` | `Date \| DateRange \| null` | `null` | Initial uncontrolled value. | | `onValueChange` | `(value: Date \| DateRange \| null) => void` | `—` | Receives Date or DateRange depending on mode; the app usually stores ISO. | | `label` | `ReactNode` | `—` | Visible label; it also names the panel when dialogLabel is not set. | | `description` | `ReactNode` | `—` | Help text connected through aria-describedby. | | `error` | `ReactNode` | `—` | Sets aria-invalid and is announced in an aria-live region. | | `required` | `boolean` | `false` | Adds the visual asterisk and the field's required state. | | `disabled` | `boolean` | `false` | Disables the button and prevents the panel from opening. | | `placeholder` | `string` | `—` | Text when there is no value; shown in the faint color. | | `min / max` | `Date` | `—` | Days outside the range are disabled. | | `defaultMonth` | `Date` | `valor u hoy` | Month the panel opens on; defaults to the value or today. | | `dialogLabel` | `string` | `label` | Accessible name of the panel; defaults to label when it is a string. | | `className` | `string` | `—` | Classes for the field container. | ## Accessibility - The field is a button with aria-haspopup="dialog", aria-expanded and aria-controls pointing to the panel. - The panel is anchored to the field (no portal); Escape closes it and returns focus to the button. - label, description and error are connected through aria-labelledby and aria-describedby; the error uses aria-live. - The visible value is formatted with Intl; the controlled state keeps ISO in the application. ## Sources - Catalog page: https://koten.codehive.com.co/components/date-picker - Markdown: https://koten.codehive.com.co/md/components/date-picker.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "Dialog" description: "A modal dialog for confirming or editing without leaving the page. It traps focus, closes with Escape and returns focus to the trigger." kind: component id: C-031 registry: "dialog" docs: "https://koten.codehive.com.co/components/dialog" markdown: "https://koten.codehive.com.co/md/components/dialog.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/dialog.json" language: en --- # Dialog · ダイアログ > Component C-031 in the Koten UI catalog. A modal dialog for confirming or editing without leaving the page. It traps focus, closes with Escape and returns focus to the trigger. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/dialog.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/dialog.json ``` ## Files - `@/components/ui/dialog.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Requirements - **portal** — Portaled popup: The popup mounts inside BaseDialog.Portal, outside the document flow. Do not nest it in containers with overflow or in layers with their own z-index. ## Reference - Upstream primitive: https://base-ui.com/react/components/dialog ## Examples ### Confirmation with footer Title, description and a footer with actions; the close control is appended at the end of the footer. ```tsx Open dialog} title="Order details" description="KURA-0142 · KURA Distribution" closeLabel="Close" footer={ <> } >

The order leaves the Tokyo warehouse on 22 Oct.

 ``` ### Without actions Without a footer the dialog only informs; the header button still closes it. ```tsx View note} title="Stock note" description="Written by the Osaka warehouse team" closeLabel="Close" >

Reserved units are held for 48 hours.

 ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `trigger` | `ReactElement` | `—` | The element that opens the dialog; Base UI merges its props with the trigger. | | `title` | `ReactNode` | `—` | Required: BaseDialog.Title provides the accessible name. | | `description` | `ReactNode` | `—` | Optional; it is associated with the dialog as its description. | | `children` | `ReactNode` | `—` | The dialog body, inside the scrollable area. | | `footer` | `ReactNode` | `—` | Footer actions; the close button using closeLabel is appended at the end. | | `closeLabel` | `string` | `—` | Accessible text for the close control in the header and footer. | | `className` | `string` | `—` | Merged with the default max width and border. | ## Accessibility - The name comes from title and the context from description; in practice both are required. - Focus stays trapped in the popup; Escape, the close button and the backdrop close it. - On close, focus returns to the element that opened the dialog. - While open, the rest of the page is removed from the keyboard order. ## Sources - Catalog page: https://koten.codehive.com.co/components/dialog - Markdown: https://koten.codehive.com.co/md/components/dialog.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "Drawer" description: "A side panel for editing or filtering without losing the table behind it. It keeps context, enters from one side and returns focus on close." kind: component id: C-032 registry: "drawer" docs: "https://koten.codehive.com.co/components/drawer" markdown: "https://koten.codehive.com.co/md/components/drawer.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/drawer.json" language: en --- # Drawer · ドロワー > Component C-032 in the Koten UI catalog. A side panel for editing or filtering without losing the table behind it. It keeps context, enters from one side and returns focus on close. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/drawer.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/drawer.json ``` ## Files - `@/components/ui/drawer.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Requirements - **portal** — Portaled popup: The panel mounts inside BaseDrawer.Portal with its backdrop. Do not nest it in overflowing containers or it will be clipped. ## Reference - Upstream primitive: https://base-ui.com/react/components/dialog ## Examples ### Side filters Enters from the right with a description and a footer action; the maximum width is 480 px. ```tsx Open drawer} title="Order filters" description="Apply and close to see the results." closeLabel="Close" side="right" footer={} >

The drawer keeps the table context and is meant for side editing.

 ``` ## Props | Prop | Type | Default | Notes | | --- | --- | --- | --- | | `trigger` | `ReactElement` | `—` | The element that opens the panel; it receives the trigger props. | | `title` | `ReactNode` | `—` | Required: it gives the drawer its accessible name. | | `description` | `ReactNode` | `—` | Optional; explains what the panel does. | | `children` | `ReactNode` | `—` | The scrollable content of the panel. | | `footer` | `ReactNode` | `—` | Actions pinned to the bottom; no automatic close control is added. | | `closeLabel` | `string` | `—` | Accessible text for the header close button. | | `side` | `left \| right` | `right` | The side the panel enters from; it also sets the swipe direction. | | `className` | `string` | `—` | Merged with the max width and the border of the active side. | ## Accessibility - Title and description name the panel and explain its purpose. - Focus enters the panel, stays trapped, and returns to the trigger when Escape closes it. - The header close control is an icon, so closeLabel is required. - The swipe gesture follows side and does not replace the close button. ## Sources - Catalog page: https://koten.codehive.com.co/components/drawer - Markdown: https://koten.codehive.com.co/md/components/drawer.md - Repository: https://github.com/codehive-colombia/koten --- --- title: "EmptyState" description: "Explains why there is no data and offers a way out. The title names the absence; the description and action show how to continue." kind: component id: C-023 registry: "empty-state" docs: "https://koten.codehive.com.co/components/empty-state" markdown: "https://koten.codehive.com.co/md/components/empty-state.md" install: "npx shadcn@latest add https://koten.codehive.com.co/r/empty-state.json" language: en --- # EmptyState · 空状態 > Component C-023 in the Koten UI catalog. Explains why there is no data and offers a way out. The title names the absence; the description and action show how to continue. > Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031). ## Install Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project. ```bash # Node npx shadcn@latest add https://koten.codehive.com.co/r/empty-state.json # Bun bunx shadcn@latest add https://koten.codehive.com.co/r/empty-state.json ``` ## Files - `@/components/ui/empty-state.tsx` - `@/lib/koten/cn.ts` - `@/lib/koten/format.ts` - `@/lib/koten/intl.ts` - `@/lib/koten/labels.ts` - `@/lib/koten/provider.tsx` ## Examples ### With an action The action takes the user out of the empty state; without it, the block only informs. ```tsx Clear filters} /> ``` ### Custom icon, no action In a read-only panel, an icon, title and a short hint are enough. ```tsx